Copyright: Copyright 1995, Novell, Inc.


WordPerfect InfoCentral ALM Functions

Add Connection

Add Object

Execute Macro

Get Category Info

Get Current iBase

Get Last Error

Get Token

GroupWise Import-Export

Locate Connection

Locate Object

Open iBase

Read Connection

Read Connection Info

Read Object

Save iBase

Settings

Update Connection

Update Object


Add Connection

Platform	MS Windows

Action	Connect two objects in the current InfoCentral iBase.

Input Parameters

PrimaryObjectID	The ObjectID of the primary object to be connected.  Type Required Text

SecondaryObjectID	The ObjectID of the object to be connected to the primary object.  This parameter may also be the name of a file to connect to the PrimaryObjectID.  Type Required Text

If this parameter specifies a file, the following applies:

      	1) The filename must contain at least one non-numeric character (i.e. drive, path, file extension or "." after the filename).  For example, if C:\Docs is the current drive and directory, the file C:\Docs\12345. can be specified as C:\Docs\12345, 12345., C:12345, or  \Docs\12345; but, 12345 would be invalid because there are no nonnumeric characters in the filename

                          	2) The file must already exist,

                           	3) PrimaryRelationship must specify the connection description between the two objects,

                          	 	4) SecondaryRelationship and FieldValues are ignored.

 	PrimaryRelationship	The relationship of the primary object to the secondary object.  Type Required Text

  	SecondaryRelationship	The relationship of the secondary object to the primary object (if applicable for a particular connection).  Type Required Text

  	FieldValues(s)	A list of connection field values in a string.  Each value must be specified, and listed in the order they are found on the  connection 	information dialog, or as the FieldNames that are returned by the Read Connectin Info function.  The  FieldValues must be delimited with the delimiter specified in the Settings function.  Type Required Text

Output Parameters

   	ConnectionID	Returns the ID of the connection just created.  Type Required Number

Flows

   	 Added	The connection was successfully added to the iBase.

   	 Failed	The connection was not added to the iBase.


Add Object

Platform	MS Windows

Action	Add an object to the current InfoCentral iBase.  If a duplicate object already exists, another one will be created.

Input Parameters

Category	The category name of the new object.  Type Required Text

FieldValue(s)	A list of object field values in a string.  Each value must be specified, and listed in the same order as the FieldNames that are returned by the Get Category Info function.  The FieldValues must be delimited with the delimiter specified in the Settings function.  See the output parameter FieldValues on Read Object for information on the values for Radio Button and Check Box fields.  Type Required Text

Output Parameters

ObjectID	Returns ObjectID of the object just added.  Type Required Number

Flows

Added	The object was successfully added to the iBase.

Failed	The object was not added to the iBase.


Execute Macro

Platform	MS Windows

Action	Executes an InfoCental macro.

Input Parameters

MacroName	The name of the macro file to execute.  This macro file must be a precompiled macro file (extension must be .MXE).  Type Required Text

fOptions	Flags indicating which window should have the focus when this API has completed.    Type Required Text

Possible values are:

WPIC_MACROEXECUTE_FOCUSTOAPP   "2"

After executing the macro, set the focus to the window which had the focus before this API call was invoked.  This value will be used if an invalid value is specified for the fOptions parameter.

WPIC_MACROEXECUTE_FOCUSTOWPIC  "5"

After executing the macro, leave the focus on the window with the current focus within InfoCentral.

 Flows

Executed	The macro was executed successfully.

Failed	The macro was not executed.


Get Category Info

Platform	MS Windows

Action	Retrieves the field names for a specified category.

Input Parameters

CategoryName	The name of the category to query.  If this field is blank, then all categories accessible by the user are returned.  Type Required Text

Output Parameters

CategoryFields	A string of field names to be returned.  The field names will be separated by the delimiter specified in the Settings function.  If CategoryName was blank, then CategoryFields will contain a delimited string of all category names in the iBase accessible by the user.  Type Required Text

Flows

Found	The category names or fields were successfully read from the iBase.

 	NotFound	The category names or fields were not read from the iBase due to an error.


Get Current iBase

Platform	MS Windows

Action	Retrieve the name of the last iBase accessed by InfoCentral.

Input Parameters

LanguageKey	The language version of InfoCentral to be queried.  If this value is blank, the following versions of InfoCentral are queried in the following order until a valid language version of InfoCentral can be  located.  Type Required Text

 (Note: This is the same order used by this subsystem to start InfoCentral if InfoCentral needs to be started).

1) A language version of InfoCentral using a language key specified by the key value for: WPConfig\\InterfaceLanguage\Preferred in the Windows Registration DataBase.  If not available, then,

2) The last language version of InfoCentral that has been executed.  This is determined by the key value for: WPConfig\Apps\ICWin??\Language in the Windows Registration DataBase, where ?? is the appropriate language version of InfoCentral.

Output Parameters

iBaseName	The fully qualified name of the iBase last accessed by the specific language  version of InfoCentral.  This name can be used on subsequent calls to Open iBase.  Type Required Text

Flows

Retrieved	The iBaseName was successfully retrieved.

Failed	The iBaseName could not be retrieved.


Get Last Error

Platform	MS Windows

Action	Retrieve the error code from the last call to this subsystem.

Output Parameters

LastErrorCode	The error code from the last call to this subsystem.  This is an unsigned long number, not a character string as with other APIs.  Type Required Text

Possible values are:

WPICAPI_NO_ERROR = 1  -  No errors occured during last call to this subsystem.

WPICAPI_ERROR = 2  -  A general failure occured in the subsystem.	 No additional information is available.

WPICAPIERROR_BUFFER_INPUTOVERFLOW = 10  -  One of the input parameters (Inputs:) was too long for the internal buffers.  Try specifying APIFileName on Settings (if available for the failing function) or reduce the length of the input parameter which is too long.  The maximum length of any input or output parameter is specified by the parameter MaxStringLength on the call to Settings.

WPICAPIERROR_BUFFER_OUTPUTOVERFLOW = 11  -  One of  the output parameters (Outputs:) was too long to place in an internal buffer or one of the output parameters provided.  Try specifying APIFileName on Settings (if available for the failing function) to have the data returned via the file rather than via the output parameter.  The maximum length of any input or output parameter is specified by the parameter MaxStringLength on the call to Settings.

WPICAPIERROR_OUT_OF_MEMORY = 12  -  An error occured when this subsystem requested additional memory from the operating system.  Closing other applications that are running may help solve the problem.

WPICAPIERROR_DLLLOAD_WPICHOOK = 100  -  Unable to load WPICHOOK.DLL.  See solution for WICAPIERROR_INFOCENTRAL_START.

WPICAPIERROR_DLLLOAD_WPICOTHER = 101  -  Unable to load other WPIC DLLs.  See solution for  WPICAPIERROR_INFOCENTRAL_START.

WPICAPIERROR_INFOCENTRAL_START = 110  -  Unable to start InfoCentral.  Make sure that InfoCentral was properly installed.  This error may be a result of  incorrect entries in the Registration DataBase, see WPICAPIERROR_REGDATABASE for more information.

WPICAPIERROR_REGDATABASE = 120	 -  Make sure that the InfoCentral entries in the Windows Registration DataBase are present and correct.  You could reinstall InfoCentral to make sure the entries are correct, or edit the registration database.  To view and/or edit the Windows Registration DataBase, run the windows program "RegEdit" with the "/V" parameter, then search for the key "ICWIN".

WPICAPIERROR_IBASENOTFOUND = 130  -  The iBaseName specified is invalid, had missing files, or is corrupt.

WPICAPIERROR_PASSWORDINVALID = 140  -  The password specified was invalid.

WPICAPIERROR_CATEGORY =	151  -  A required category is missing from the current iBase.  This may occur if GroupWise Import-Export is specified and the iBase does not have an Event category type.

WPICAPIERROR_DIDCANCEL = 152  -  The user canceled from the requested operation.  This could occur for instance if the user selected cancel while GroupWise Import-Export was busy.

   	WPICAPIERROR_FILE_ERROR = 153  -  A file was not able to be created or opened for write in the InfoCentral "local" directory.

WPICAPIERROR_DATA_ERROR = 154  -  An error occured accessing data within InfoCentral.  Most likely the iBase is corrupted.  Run HouseKeeping to verify and fix the iBase.

WPICAPIERROR_EMAIL_NOTFOUND = 155  -  An email package supported by GroupWise Import-Export was not able to be loaded.

Flows

Retrieved	The last error code was retrieved.

Failed	The last error code could not be retrieved.


 Get Token

Platform	MS Windows

Action	Retrieves a token from a string of tokens.

Input Parameters

StringOfTokens	A string of tokens, each token delimited by the delimiter specified in Settings.  Type Required Text

TokenIndex	The index of the token to retrieve.  The first token is "1", the second is "2" and so on.  Type Required Number

Output Parameters

Token	The token in the TokenIdx position within StringOfTokens.  Type Required Text

Flows

Retrieved	The token was retrieved.

Failed	The token was not found, or an error occurred.


GroupWise Import-Export

Platform	MS Windows

Action	Imports and/or exports InfoCentral Events from/to Novell GroupWise.

Input Parameters

DaysPrior	The number of days prior to the current date to import or export information.  Type Required Text

DaysAfter	The number of days after the current date to import or export information.  Type Required Text

ImportAppointmentsFlag	Indicates if appointments should be imported from Novell GroupWise into InfoCentral.  Type Required Text

Possible values are:

1 = Import appointments

0 = Don't import appointments

ImportTasksFlag	Indicates if tasks should be imported from Novell GroupWise into InfoCentral.   Type Required Text

Possible values are:

1 = Import tasks

0 = Don't import tasks

ExportAppointmentsFlag	Indicates if appointments should be exported from 	InfoCentral into Novell GroupWise.  Type Required Text

Possible values are:

1 = Export appointments

0 = Don't export appointments

ExportTasksFlag	Indicates if tasks should be exported from InfoCentral into Novell GroupWise.  Type Required Text

Possible values are:

1 = Export tasks

0 = Don't export tasks

Flows

Success	The import/export was successful.

Failed	An error occured during import export


Locate Connection

Platform	MS Windows

Action	Locates connection(s) in the current InfoCentral iBase matching the search criteria.

Input Parameters

PrimaryType	The category name(s) of the primary objects of connection(s) to locate. If  more than one category name is specified, each must be separated by the delimiter specified in the function Settings.  For specific category types specify TYPE=CategoryTypes for this field. CategoryTypes can be one or more of the following (each separated by the delimiter character): PERSON, ORGANIZATION or THING.  Note FILE may be specified for SecondaryCategory, but not PrimaryCategory). If this field is blank, then all categories will be considered a match for this parameter.  Type Required Text

SecondaryType	The category name(s) of the secondary objects of the connection(s) to locate.  If  more than one category name is specified, each must be separated by a delimiter specified in the function Settings.  For specific category types specify TYPE=CategoryTypes for this field.  CategoryTypes can be one or more of the following (each separated by the delimiter character): PERSON, ORGANIZATION, THING, or FILE). If this field is blank, then all categories will be considered a match for this parameter.  Type Required Text

PrimaryRelationship	Relationship of the PrimaryCategory to the SecondaryCategory.  If blank, all PrimaryRelationship descriptions found will be considered a match.  Type Required Text

SecondaryRelationship	Relationship of the SecondaryCategory to the PrimaryCategory (if applicable).  If blank, all SecondaryRelationship descriptions found will be considered a match.  Type Required Text

ObjectID	Limit the search for PrimaryRelationships to the PrimaryObjectID (i.e. return only objects connected to the PrimaryObjectID that meet the other search criteria.  Type Required Number

Output Parameters

   	NumFound	The number of connections found that match the search criteria.  Type Required Text

ConnectionID	A string of ConnectionIDs representing all the connections matching the search criteria.  These ConnectionIDs are only valid until a new connection is added or deleted to the current iBase. The ConnectionIDs will be delimited by the delimiter specified in the Settings function. These ConnectionIDs must be used by other functions that require a ConnectionID as an input parameter. Use the Get Token function to retrieve a ConnectionID in the TokenIdx position within the string of ConnectionID(s).  Type Required Number

Flows

Found	One or more connections were located.

NotFound	No connections were found matching the search criteria.  This value is also returned if an error occurs.


Locate Object

Platform	MS Windows

Action	Locates object(s) in the current InfoCentral iBase matching the search criteria.

Input Parameters

CategoryName	The category name(s) of the object(s) to locate.  If more than one category name is specified, each must be separated by a delimiter specified in the Settings function.  For specific category types specify TYPE=CategoryTypes for this field.  CategoryTypes can be one or more of the following (each separated by the delimiter character): PERSON, ORGANIZATION, THING, or EVENT).  If this field is blank, then all categories will be included in the search (i.e. similar to Choosing Find, FastFind, and FindAll in InfoCentral).  Type Required Text

ObjectName	The name of the object to locate (as a user would enter in the FastFind dialog entry field).  Type Required Text

The following keywords may be used in this field:

#DISPLAYLIST:

Specifies that all objects at all levels in the current InfoCentral display list matching the CategoryName(s) specified will be returned.  TYPE=CategoryTypes cannot be used when this keyword is specified.  No objects will be returned if the current InfoCentral tab is a calendar tab.

#DISPLAYLISTSELECTED:

Specifies that the currently selected object in the current InfoCentral display list will be returned.  If this keyword is specified, then CategoryName is ignored.  No objects will be returned if the current InfoCentral tab is a calendar tab.

Output Parameters

NumberOfObjectsFound	The number of objects found that match the search criteria.  Type Required Number

ObjectID	A string of ObjectIDs representing all the objects matching the search criteria.  The ObjectIDs will be delimited by the delimiter specified in the Settings function.  These ObjectIDs must be used by other functions that require an ObjectID as an input parameter.  Use the Get Token function to retrieve an ObjectID in the TokenIdx position within the string of ObjectID(s).  If APIFileName was not blank on the last call to Setting, the ObjectID will be written to the APIFileName file and this parameter will be blank.  Type Required Text

Note: There may be multiple lines in the APIFileName file.  A new line character is treated just like a delimiter character.  No line in the APIFileName will be longer than 254 characters.  See Settings for more information.  This file of ObjectIDs may then be used on a call to Read Object as a replacement the ObjectID parameter.

Flows

Found	One or more objects were located.

NotFound	No objects were found matching the search criteria.  This value is also 	returned if an error occurs.


Open iBase

Platform	MS Windows

Action	Opens an InfoCentral iBase.  The current iBase will be closed.

Input Parameters

iBaseName	The name of the iBase to open.  This can be a fully qualified iBase name.  This function will try to open the iBaseName relative to the current directory, not the last directory used to open an iBase (as is the case with the InfoCentral File, Open dialog.  We recommend you specify a fully qualified iBaseName to avoid confusion.  Type Required Text

Password	The password for iBaseName.  If the iBaseName is not password protected, this parameter is ignored.  Type Required Text

Flows

Opened	The iBase was successfully opened.

Failed	The iBase was not opened.


Read Connection

Platform	MS Windows

Action	Reads field values for a link from the current InfoCentral iBase.

Input Parameters

ConnectionID	The ID of the connection to query.  This value must be retrieved by a call to Locate Connection.  The ConnectionID of a connection may change when connections are added or deleted.  Type Required Number

FieldName(s)	A string of connection field names to be returned.  The field names must be separated by the delimiter specified in the Settings function.  Specify a blank string "" for this value to return all fields for the object.  Type Required Text

Output Parameters

FieldValue(s)	A string of connection field values.  Each value will be separated by the delimiter specified in the Settings function.  Type Required Text

Flows

Read	The connection was successfully read from the iBase.

Failed	The connection was not read from the iBase.  This value will also be returned when an error occurs.


Read Connection Info

Platform	MS Windows

Action	Retrieves the field names for a specified connection.

Input Parameters

ConnectionID	The ID of the connection to query.  This value must be retrieved by a call to Locate Connection.  The ConnectionID of a connection returned from Locate Connection may change when connections are added or deleted.  Type Required Number

Output Parameters

FieldName(s)	A string of connection field names.  The field names will be separated by the delimiter specified in the Settings function.  Type Required Text

Flows

Read	The connection fields were successfully read from the iBase.

Failed	The connection fields were not read from the iBase.


Read Object

Platform	MS Windows

Action	Reads field values for one or more objects from the current InfoCentral iBase.

Input Parameters

ObjectID	The ID(s) of the object(s) to be read.  Use the Locate Object function to get the ObjectID(s) given an object name.  If APIFileName was not blank on the last call to Settings, and ObjectID(s) (this parameter) is blank, then the ObjectID(s) will be read from the file APIFileName, rather than obtained from this parameter.  Type Required Number

Note: There may be multiple lines in the APIFileName file.  A newline character is treated just like a delimiter character.  No line in the APIFileName will be longer than 254 characters.  See Settings for more information.

FieldNames	A string of object field names to be returned. The field names must be separated by the delimiter specified in the function Settings.  Specify a blank string "" for this value to return all fields for the objects specified.  Type Required Text

Output Parameters

FieldValue(s)	A string of object field values.  Each value will be separated by the delimiter specified in the function Settings.  If more than one ObjectID is specified, each object will be separated by a Carriage Return (new line) followed by a Line Feed character combination (i.e.  hex 0D + hex 1B).  This data can also be returned via the APIFileName if needed  (see Settings for more information about APIFileName).  If APIFileName was not blank on the last call to Settings, the FieldValues will be written to the APIFileName file and this parameter will be blank.  Each line in the APIFileName file will represent the FieldValues for one object.  See Settings for more information.  Type Required Text

Radio Button and Check Box fields:

Radio Button fields return the sequential number of  the button that is currently selected ("1", "2", "3", ...).  The sequential number of the button is the "choice#" found in the field setup properties dialog for a field.  The sequential number starts at "1" for the top left choice of a field, increasing from left to right across a line, then continuing to the next line (left to right, top to bottom).

Check Box fields return a value which is a bitfield indicating which check boxes are checked.  The least significant bit in the bitfield represents the first check box within a check box field, the second bit represents the second check box in the first row of the field and so on.  The sequence of the check boxes within a field are left to right across rows, then top to bottom.  If the bit is set, then the check box is selected, if the bit is not set (or cleared) the check box is not selected.  See below for an explanation of bitfields.  Following is an example of a check box field:

We have a check box field called "Alarm Notification" and the possible check box choices within the field are listed in the following order in the object information dialog: "When Due", "3 Min.  Before", "5 Min Before", "10 Min.  Before" and "15 Min.  Before".  The bits representing each check box in the field would be:

Bit

Value  Representation

==================

1	When Due

2	3 Min. Before

4	5 Min Before

8	10 Min. Before

16	15 Min. Before

32	not used

64	not used

128	not used

256	not used

If the check boxes When Due, 5 Min. Before, and 10 Min Before are selected, then the value returned for the field would be "13" (1 + 4 + 8 = 13).

Bitfields:

A bitfield is a set of bits in a single unit (or value).  Each bit can be viewed  as a position that represents a unique entity.  The value of the bit can be either set (equal to 1) or not set (cleared or equal to 0).  The value represented by the bit can be determined by raising 2 by the power of the position of the bit.  The least significant bit would be position 0 (zero).  Therefore the values of the bits would begin with 1 in position 0, 2 in position 1, 4 in position 3, 8 in position 4 and so on (1, 2, 4, 8, 16, 32, 64,...).  The value of the bitfield is the sum of the values represented by each bit.  In our case if the bit in the fourth position is set, then the fifth check box has been checked and the value representing that bit is 8 (2**4=8).

Flows

Read	The object was successfully read from the iBase.

Failed	The object was not read from the iBase.


Save iBase

Platform	MS Windows

Action	Saves the contents of the current InfoCentral iBase.

Parameters	The Save iBase function has no parameters

Flows

Saved	The iBase was successfully saved.

Failed	The iBase was not saved.


Settings

Platform	MS Windows

Action	Specifies settings to be used on subsequent calls to functions in the WPInfoCentral API module.  If this function is not invoked, then the default values listed will be used.

Input Parameters

Delimiter	The delimiter to be used with all delimited strings.  The delimiter must be only one character in length.  The delimiter cannot be a new line (hex 0D) character, a line feed (hex 0A) character, an escape character (hex 1B) character, or any combination of these characters.  Type Required Text

APIFileName	If not a blank string (i.e. ""), this file name will be used in place of certain parameters on selected function calls (input and/or output parameters).  Each call that supports the APIFileName will specify which parameters support the APIFileName.  This file name must be fully qualified.  This may not be any file matching the following file pattern:   "WPIC API.*".  When this file is used in the place of an input parameter, lines must not be longer than 254 characters.  A new line (Carriage Return + Line Feed) character is treated just like a "Delimiter"  character.   Type Required Text

MaxStringLength	The maximum number of characters allowed on any input or output parameter in this subsystem.  This value may not exceed WPICAPI_MAX_STRING_LENGTH (approximately 32K).  Type Required Text

Default values:

Delimiter    "," (comma)

APIFileName    ""  (blank string)

MaxStringLength    WPICAPI_MAX_STRING_LENGTH (approximately 32K).

Flows

Set	The settings were successfully set.

Failed	An error occurred.  Possible causes include:

1) MaxStringLength exceeds WPICAPI_MAX_STRING_LENGTH,

2) The delimiter exceeds one character in length, or contains an invalid character,

3) The APIFileName exceeds 255 characters.


Update Connection

Platform	MS Windows

Action	Updates a connection in the current InfoCentral iBase.

Input Parameters

ConnectionID	The ID of the connection to be updated.  This value must be retrieved by a call to Locate Connection.  The ConnectionID of a connection may change when connections are added or deleted. Type Required Number

FieldValue(s)	A list of connection field values in a string.  Each value must be listed in the order of the field names that are returned by	 Read Connection Info.  The FieldValues must be delimited with the delimiter specified in the function Settings.  If a value is blank, the value for the corresponding field will also be blanked for the connection in the iBase.  The Read Connection function should be called  to fill in the field values, then modify the values, then call this function to update the InfoCentral connection.  Display only or static fields must be specified (i.e. a blank value), but are not modified in record.  Type Required Text

Flows

Updated	The connection was successfully updated in the iBase.

Failed	The connection was not updated in the iBase.


Update Object

Platform	MS Windows

Action	Update an object in the current InfoCentral iBase.

Input Parameters

ObjectID	The ID of the object to be updated.  Use the Locate Object function to get the ObjectID given an object name.  Type Required Number

FieldValue(s)	A list of object field values.  Each value should be listed in the same order as the field names that are returned by Get Category Info.  The FieldValues must be delimited by the delimiter specified in the function Settings.  If a specific value is blank, the corresponding value will also be blanked for the object in the iBase.  You should call Read Object to fill in the field values, then modify the values you wish to modify, then call this function to update the InfoCentral object.  Type Required Text

Flows

Updated	The object was successfully updated in the iBase.

Failed	The object was not updated in the iBase.