Using System Settings

Using System Settings

About System Settings

System settings are special configuration variables stored in the VY_USERSETTING table. The values of system settings are used by Vine applications much the same as the operating system's environment variables are used by Windows applications. System settings help to fine-tune a Vine tool in accordance with the specifics of the Vine system where the product is being installed to.

System settings can be created, for example, using Vine Web Administrator’s Console.

Some standard uses of system settings include: setting a user’s main group (SETTINGID=1), setting a user’s workspace (SETTINGID=2), Setting a Home Map (SETTINGID=100001).

Example:

A Vine plug-in is designed to email sales reports to the persons included in a specific collection. The name of that collection can be hardcoded in the plug-in, but it is more flexible to create a system setting, for instance, "Report Recipients". The value of that setting can be set to any existing collection of persons, e.g. "Marketing Department". This way the plug-in will send reports to the persons included in the Marketing Department collection.

Installing System Settings

Before a custom add-on application can use a system setting, the setting should be installed to the VY_USERSETTING table. The add-on setup macro can add it by calling the CreateSystemSetting procedure from the VineyardMgr package:

VineyardDB.VineyardMgr.CreateSystemSetting(SettingName varchar2, SettingType varchar2, SettingID number, SettingValue varchar2);

The SettingName, SettingType and SettingValue parameters must be provided. The CreateSystemSetting procedure creates a new entry in the VY_USERSETTING table and assigns proper values to the mandatory generic fields (STATUS, CHANGEDATE, CHANGEUSER...). The UserID field is assigned zero for system settings.

VineyardDB.VineyardMgr.CreateSystemSetting ('VY_Report Recipients', 'VY_COLLECTION', NULL, 999999999);

• SettingName is the name of a system setting. It should be unique and have a prefix stating the producer. The "VY_" prefix stands for Vine.

• SettingType is the type of a system setting. It can be the name of a database table, such as VY_COMPANY, VY_EVENTTYPE or STATIC.

• SettingID can be NULL. In this case, the procedure will create SettingID for the new setting. It is possible to provide SettingID but then the programmer must ensure its correctness.

• SettingValue is the value of a system setting. If SettingType is an object table, like VY_COMPANY then the setting's value can be the ID of any company stored in the database. If it is a parameter table, like VY_EVENTTYPE then its value can be chosen from the IDs of available parameters, i.e. the entries of the VY_EVENTTYPE table. If SettingType is STATIC then its value can be any text string.

Note that the value of a system setting can be changed using Vine Administrator’s Web Console.

Getting System Settings

The value of the installed setting can be retrieved by an add-on application using the GetUserSetting function from the VYUtilAPI package:

Recepients:=vineyarddb.VYUtilAPI.GetUserSetting(0,'VY_Report Recipients');

See also the example to the VYUtilAPI.GetUserSetting function's description.