Upgrading and migrating : Converting encyclopedias to current version : Changes to Microsoft Visual Basic Application macros : Microsoft SQL Server Encyclopedia Access : AccessDefinition
  
AccessDefinition
The AccessDefinition function finds or creates, opens, or open-locks a definition.
int AccessDefinition(
LPSAIDENT ddPrevDef, /* Input: previous definition */
LPCTSTR lpName, /* Input: definition name */
LPWORD lpwMinorType, /* Input: definition type */
DWORD dwCommand, /* Input: combination of commands */
LPSAIDENT lpidDefinitionRet, /* Output: accessed definition id */
LPSAHANDLE lphDefHandleRet, /* Output: accessed definition handle */
LPWORD lpwIsDefNew) /* Output: indicates the creation of the definition */
Parameters
ddPrevDef
Pointer to the previous definition's ddId. It can be NULL.
lpName
Name of definition to be opened. It can be a qualified name.
LpwMinorType
Pointer to the minor type of the definition to be opened.
dwCommand
Specifies the action to take. The following values can be combined by using the bitwise OR operator:
Value
Meaning
IMF_DEFACCESS_CREATE
If definition attempting to be accessed couldn't be found, create it.
IMF_DEFACCESS_OPEN
Open definition.
IMF_DEFACCESS_LOCK
Lock the definition being opened. Used in conjunction with IMF_DEFACCESS_OPEN.
lpidDefinitionRet
Pointer to the opened/created definition’s ddId.
lphDefHandleRet
Pointer to the opened/created definition’ s handle.
lpwIsDefNew
Pointer to a variable indicating whether or not we created this definition.
Return values
If the function succeeds, the return value is IM2XE_OK.
If the function fails, the return value is IM2XE_*. For information on the returned error, consult IM2XDEF.H located in the SADESIGN directory.
Remarks
The command to find the definition is implied. In other words this function can be invoked with a dwCommand of 0 to find a definition.
The AccessDefinition function sets its own critical region and was designed to replace sequences of the following types:
▪FindDefinition, CreateDefinition
▪SAFindDefinition, CreateDefinition, OpenDefinition
▪FindDefinition, OpenDefinition
▪FindDefinition, OpenLockDefinition
▪CreateDefinition
When AccessDefinition is required to create a definition, it will actually write a record to the database. The function CreateDefinition did not (and still does not) do this; a call to SaveDefinition was needed to actually write the record to the database. Thus, any extant code sequence which used to call CreateDefinition (creates a memory definition block) and later decide whether to call SaveDefinition (writes out the record) or not, will have to be modified so that, if it is decided not to actually create this record, the code must now call DeleteDefinition to remove the unwanted record.
Microsoft Visual Basic Application macros that use IMF calls may require adjustment. The following IMF calls have been affected by the support for SQL Server databases:
▪SAGetEncyclopediaPath
The problem with using this ISAImf call is the same as for Encyclopedia.FullName, instead of a folder reference, a file reference is supplied. This is due to the fact that an encyclopedia is now referenced through a .UDL file and not stored within a folder. This is likely to be used simply to provide information and should not present a problem.
▪Encyclopedia.Name
This has been difficult to trace, but normally used as information about the name of an Encyclopedia. The output will identify the UDL filename and not a subdirectory.
Note that the ISAImf call SAGetEncyName returns the SQL Server's Database Name and not simply the UDL filename.
▪Encyclopedia.Fullname
As for SAGetEncyclopediaPath, a filename is returned and not a subdirectory name.