This chapter contains instructions for installing and testing spatial and user-defined data types. Install and debug your code in a test environment before you install in the production environment. The installation process builds both the local server and the Star Server with user-defined data types (because both these servers are defined as the same image).
|
|
|
Ingres processes access the new data types and functions by means of a dynamic linked library (DLL), whose entry point is the routine IIudadt_register().
Installing a new data type or function consists of building the OIUDTNT DLL using the User Defined Data Type Linker (iilink.exe) and copying the DLL into the %II_SYSTEM%\ingres\bin directory. The User Defined Data Type Linker prompts for the location of the source and library files to be used and backs up the existing DLL before replacing it.
Optionally, spatial objects or demo user defined data types can be installed using the User Defined Data Type Linker.
|
|
|
Ingres processes access the new data types and functions by means of a shared image, whose entry point is the routine IIudadt_register(). Installing a new data type or function consists of building the shared image and defining II_USERADT to point to the location of the shared image.
|
|
|
Ingres provides a template command file for building the shared image for use in a test installation. The template is located in the following file:
II_SYSTEM:[INGRES.LIBRARY]II_USERADT_BUILD.COM
This template, with comments, follows:
$ inst := 'f$trnlnm("II_INSTALLATION")
$ if inst .eqs. ""
then
$ inst_code := <production>
$ else
$ inst_code = inst
$ endif
$ Write sys$output "Building Sharable Image for User Defined Datatypes for ''inst_code' installation"
$ if f$getsyi("hw_model") .lt. 1024
$ then
$!
$! VAX version
$!
$ macro/object=ii_system:[ingres.library]ii_useradt_xfer.obj -
ii_system:[ingres.library]ii_useradt_xfer.mar
$ link/share=ii_system:[ingres.library]iiuseradt'inst'/sysshr -
sys$input/opt /nodebug 'p1'
!
! This CLUSTER statement forces the transfer vector to the beginning of
! the shared image. It should not be removed.
!
Cluster = TRANSFER_VECTOR,,,ii_system:[ingres.library]ii_useradt_xfer.obj
ii_system:[ingres.library]iiclsadt.obj
!
! Replace the object module below with the object modules
! defining Installation Datatypes
!
ii_system:[ingres.library]iiuseradt.obj
!
! End of object modules defining datatypes.
!
NAME = IIUSERADT
!
! Note that the shared image id should not be changed. INGRES expects this
! level. The shared image ID can be changed ONLY by the product vendor.
!
IDENTIFICATION = "v2-000"
GSMATCH=LEQUAL, 2, 0
$ exit
$!
$ else
$!
$! Alpha version
$!
$ link/share/notrace/nodebug/ -
exe=ii_system:[ingres.library]iiuseradt'inst' SYS$INPUT/OPTION
ii_system:[ingres.library]iiclsadt.obj -
,ii_system:[ingres.library]iiuseradt.obj
NAME = IIUSERADT
IDENTIFICATION = "V2-000"
GSMATCH=LEQUAL, 2, 0
SYMBOL_VECTOR = (iiudadt_register = PROCEDURE)
SYMBOL_VECTOR = (iiclsadt_register = PROCEDURE)
$ exit
$ endif
The transfer vector for the shared image is built by the following file:
ii_system:[ingres.library]ii_useradt_xfer.mar
If it is necessary to add additional entry points to the transfer vector, add them after the IIudadt_register entry point defined in this file. If you do not, the resulting shared image does not operate correctly with Ingres.
In a production environment, remove the /debug flag and link the shared image NOTRACEBACK. Install it using the VMS Install Utility. For additional information about creating and maintaining shareable images, see the VMS documentation (in particular, the Guide to Creating Modular Procedures).
|
|
|
II_USERADT points to the location of the shared image. By default, II_USERADT points to the following executable:
ii_system:[ingres.library]iiuseradt.exe
This location is overwritten during installations of new releases of Ingres. To avoid conflicts, place your shared image in another location and redefine II_USERADT.
System Level Installation
$define/system/exec II_USERADT II_SYSTEM.[ingres.library]iiuseradt.exe
Group Level Installation
$define/group/exec II_USERADT II_SYSTEM.[ingres.library]iiuseradtxx.exe
where xx = the two-character installation code
By default, if the logical II_USERADT is not defined, Ingres looks for the following shared image:
SYS$SHARE:II_USERADT.EXE
|
|
|
Because various Ingres programs are installed with privilege, II_USERADT must be defined at EXECUTIVE mode to be visible to these installed images. This requirement presents a problem in Ingres test installations, because logical names are not defined at a SYSTEM level in test installations and the current release of VMS only sees SYSTEM-level EXECUTIVE mode logical names when invoking privileged images.
To change this behavior, you must redefine the logical name LNM$FILE_DEV at EXECUTIVE mode to include the logical name tables in which to look.
To run the test installation, issue the following command:
$ define/exec/table = lnm$process_directory- lnm$file_dev lnm$process,lnm$job,- lnm$group,lnm$system
Consult your system manager and the VMS documentation for more details.
|
|
|
To install your user-defined data types, the DBMS, RCP, and JSP executables must be relinked (loaded) using the iilink command. The iilink command prompts for the object modules to be linked into these executables. At the prompt, specify a list of object modules, an archive library, or, if your system supports it, a shared object.
On systems which support shared object access, avoid the -l form of shared object access. The executables being linked are setuid programs, and the combination of shared objects with setuid programs leads to a number of complications in dealing with multiple installations.
For the purpose of testing, you can link only the DBMS by specifying the -dbms flag when you issue the iilink command. When you link to create your production executable, omit the -dbms flag.
The iilink utility prompts for an extension for the executable filename. The default is to create standard executables. For test purposes you can add an extension to the file names. For example, if you specify "test" as the extension, iilink creates the executable iidbms.test instead of iidbms.
The iilink command can only be run by the ingres user.
Optionally, spatial objects or demo user-defined data types can be installed using the iilink utility.
|
|
|
Because your code runs as part of the DBMS Server, any bugs in your code can have severe consequences to the system. To avoid damaging production data, run your code in a test installation before you install it in the production installation.
Symbols within the DBMS Server are not available for customer use.
Because it is inconvenient during testing to have to shutdown and restart an entire installation to check out the system, Ingres has provided the field add_risk_consistency in the IIADD_DEFINITION structure. If set to the value IIADD_INCONSISTENT, this flag allows the system to startup when a newly started process does not agree with the remainder of the Ingres installation.
Caution! Running with the add_risk_consistency set to IIADD_INCONSISTENT risks the data integrity of all databases in that installation. If failures occur, it is possible that the DBMS Server cannot back out transactions from any database. This flag must be used with extreme care and must never be used in a production environment.