StudioWorks - Configuration (All Contents)

Sw4 > Configuration > Configuration (All Contents)

Configuration

The section covers various aspects of configuring your StudioWorks application.

Startup Settings

The StudioWorks application's startup settings are controlled by the startupsettings.txt file located in the APP/startupitems folder.

The startupsettings.txt file is optional. You will only need to create the file if you want to change default settings, preset properties, or control the logon process of the end users.

Logon Settings

By default StudioWorks uses the last saved logon settings when an StudioWorks application is reopened. You can force an StudioWorks application to always use specific logon settings each time it is opened. To do so you add a logon property group to the APP/startupsettings.txt file.

The following are some examples of a logon properties group that could be added to the startupsettings.txt file.

Logon settings for logging onto an Omnis data file located in the user's APP/data folder.

logon {

     damname = OMSQLDAM ;
     hostname = APP/data/localdatafile ;
     pingdatabase = FALSE ;

}

Logon Settings for logging on as the tables owner to a FrontBase database located on a server on the local area network.

logon {

     damname = FRONTBASEDAM ;
     hostname = 192.168.1.7 ;
     databasename = LiveData ;
     tablesownerlogon = TRUE ;
     pingdatabase = TRUE ;

}

Be sure to include the ; semi-colon character after each property. The semi-colon is the delimiter.

Auto Sign-In

An StudioWorks application can be configured to automatically sign-in the client when the main library is opened. The primary reason for having this feature is to be able to open a StudioWorks Omnis web application on a server without user intervention. The other reason you might do this is to save the user from needing to enter their name and password in the Sign-In window each time they open a low security application.

To configure the StudioWorks application for auto sign-in you need to do two things:

Create an encrypted autosignin.txt file.
Modify the startupsetting.txt file to include an autosignin property.

To create the autosignin.txt file:

Go to System Administration > Users
Select the user who you want to enable for auto sign-in, and click the Edit button.
In the edit user window toolbar Special menu, select Create Auto Sign-In File.

StudioWorks will create the encrypted autosignin.txt file in the APP/startupitems folder and report back to you when it is done.

To modify the startupsetting.txt file:

Using a text editor open the startupsetting.txt located in the APP/startupitems folder
Find or create a constants properties group in the file and add an autosignin property to the group.

constants {

autosignin = TRUE ;

}

Be sure to include the ; semi-colon character after each property. The semi-colon is the delimiter.

Web App Mode

A StudioWorks application can be configured to run as an Omnis web server app.

When running on a web server, the StudioWorks application needs to startup without user intervention and in the event of an error the web app must not halt code execution with an OK message or a modal prompt window. Doing so would halt the Omnis application running on the server. HTTP requests being sent to the Omnis web app server would not be processed. The server administrator would need to use remote desktop software (VNC) to connect to the server, click the OK button, so that the code would continue. Not a good thing.

To configure an StudioWorks application to run as a web application need to modify the startupsetting.txt file:

Using a text editor open the startupsetting.txt located in the APP/startupitems folder
Find or create a constants properties group in the file and add an appmode property to the group.

constants {

autosignin = TRUE ;
appmode = web;

}

Be sure to include the ; semi-colon character after each property. The semi-colon is the delimiter.

With the appmode set to web the StudioWorks framework does the following when the application is opened:

cn.$:AppMode is set to web.
errhndlr.$:DeveloperErrorPrompts is set to kFalse. This stops the error handler from opening OK debug messages for developer versions of Omnis Studio since the developer version can be run as a web app server.
errhndlr.$:PromptUsingTraceLog is set to kTrue. This causes the $promptonceLastError method to send the last error to the trace log and then open the trace log, rather than opening a modal prompt window.

You must also configure the Logon Settings and Auto Sign-In if you set the appmode to web.

Email Settings

If you are instantiating the oEmail object using the Startup_Task task variable eml you should set the applicable oConstants properties either by overridding and setting them manually in the oConstants object in your main library, or by setting them from the startupsettings.txt file.

To set the contants which apply to oEmail in your startupsettings.txt file you will need to include a constants group with properties and values as follows:

constants {

    SysAdminEmailAddr = TheSysAdminEmailAddress ;
    SysAdminFormalName = TheSysAdminFormalName ;
    SMTPServer = TheSMTPServerName ;

}

Example properties and values:

constants {

    SysAdminEmailAddr = support@vencor.ca ;
    SysAdminFormalName = Vencor Support ;
    SMTPServer = mail.vencor.ca ;

}

Alternately you can override the following methods in oConstants of your main library and return the values you want to use for your application.

$:SysAdminEmailAddr
$:SysAdminFormalName
$:SMTPServer

Folders and Files

The StudioWorks files are stored in a specific folders and files structure. Developers can change the folders and files struture but it is recommended that you stick with the default structure while you are writing your first StudioWorks application. Later on when you are ready to release the application you will have more experience with StudioWorks and it will be much easier for you to make a change to the default folders and files structure.

For purposes of documentation, StudioWorks refers to three different root folders:

APP - Is the root folder of your StudioWorks application. Your application's main library and custom module libraries are contained inside the APP folder.
OMNIS - Is the folder where the Omnis program is located. On the Mac it is normally located in the Applications folder. On Windows it is normally located in the Program Files folder.
PREFS - Is the folder where the StudioWorks stores user preferences for the StudioWorks application. On the Mac it is normally located in the ~User/Library/Preferences/Omnis/[StartupLibName] folder. On Windows it is normally located in the C:\Documents and Settings\Administrator\Local Settings\Application Data\[StartupLibName] folder.

The APP folder can be any name you or your user want to name it. Moving or renaming the folder will have zero impact on your StudioWorks application.

Enclosed in the APP folder you may find the following folders and files.

data - This optional folder is only present if the StudioWorks app is being used in single user mode with the Omnis data file and the data file is located inside the APP folder.
libraries - This folder is where the main library is stored. The libraries folder contains a modules subfolder where your StudioWorks application's custom libraries are stored.
startupitems - This folder is where the startupsettings.txt file is stored. The encrypted tablesownerlogon.txt and autosignin.txt files if applicable are located in this folder.
open_MyApp.lbs - This library file acts like an alias or shortcut file. When the library is opened it looks for the libraries folder in the same directory and then opens any libraries inside the libraries folder. Normally the only library file located at the first level of the libraries folder is the main library. (More on the main library later) The _MyApp portion of the open_MyApp.lbs file should be renamed to the name of your appliation. e.g. openClientTracker.lbs.

The open_MyApp.lbs library file could be replaced with an AutoUpdater library. You would configure the AutoUpdater library to check for any newer version files and download them from a server to the client prior to opening the main library and any of the sub-libraries or StudioWorks libraries. See StudioTips > Utilities for more information on AutoUpdater.
studioworks - This folder contains all of the StudioWorks folders and files. When StudioWorks starts up it opens all the libraries located in this folder and drills down recursively into all subfolders opening any library files it finds. You can locate the studioworks folder in your APP folder, or it can be located in the OMNIS folder or an Omnis Startup folder. When you are starting to learn StudioWorks it is easiest to keep it in the APP folder. Later on to avoid having multiple copies of StudioWorks on your computer you may want to move the studioworks folder to your OMNIS folder or an Omnis Startup folder which you can create inside the Applications (Mac) or Programs Folder (Win).

Enclosed in the PREFS folder you may find the following StudioWorks related folders:

logs - StudioWorks creates the logs folder and a subfolder inside the logs folder for each StudioWorks application. The subfolder name matches StudioWorks application's main library default name. The log files are then creates inside the subfolder.
local_prefs.df1 - StudioWorks creates a local_prefs data file where the local user preferences are then stored for the StudioWorks application. Last user who signed in, last language used, are examples of the types of information stored in the local_prefs data file.

Folders Configuration

The StudioWorks default folders configuration can be controlled in two places.

startupsettings.txt file located in the startupitems folder.
oPaths object located in the main library.

You can change the StudioWorks default folder names by adding a paths properties group to the startupsettings.txt file. The following is a sample of what you could include in the startupsettings.txt file:

paths {

OmnisStartupFolderName = My Application Name ;
PreferencesParentFolderName = My Application Name ;

}

The name of the preferences folder for your StudioWorks app will default to the $name property of your main library. If you want the preferences folder for your StudioWorks app to be a nicer looking name add an $:AppName property method to your main library Startup_Task and return the actual name of your application from that method. The oPaths object will use the return value for your StudioWorks app's preferences folder name.

; $:AppName method - add to main library Startup_Task.
Quit method 'My App Name'

You can control any of the folder locations and names by modifying methods of the oPaths object located in your main library. Only do this if you have a good reason for doing so. If a new release of StudioWorks has a modified oPaths object the intent is that you simply replace your old main library oPaths object with the new oPaths object. Modifying the oPaths object will give you more work because you will then have to compare your oPaths object with the new oPaths object and manually make the changes.

App Libraries List

The oConstants property method $:AppLibsList returns a list of libraries to be included in the application. By default this method returns a list of the following libraries:

The main library located in the APP/libraries folder
All libraries located in the APP/libraries/modules folder.
All libraries located in the studioworks folder and its subfolders.

There might be libraries in the studioworks folder which you do not want included in your application. The $:AppLibsList method lets you control the libraries which are included in your application.

It is recommended that you structure your StudioWorks application as follows:

Subclass oConstants to your main library.
Point the main library Startup_Task variable, cn, to the oConstants subclass in the main library.
Override $:AppLibsList and enter code which selects and keeps libraries to be included in your application.

; Build a list of open libraries used by the application in the order of: prefs, main, libraries, modules, shared. (not utilities)
; Return a list of all the libraries inside the APP folder and the studioworks folder . List is defined using sAppLibs_listdef.
Do inherited Returns AppLibsList

; Select the libraries which are part of this application.

; Deselect all lines.
Do AppLibsList.$search(kFalse)

; Select the main and module libraries.
Do AppLibsList.$search($ref.ismainlib=kTrue,1,0,1,0)
Do AppLibsList.$search($ref.isappmodulelib=kTrue,1,0,1,0)

; Select the SW shared libraries to include in the app.
Do AppLibsList.$search(low($ref.libname)=low('swcSysAdmin4'),1,0,1,0)

; Select the SW core libraries to include in the app.
Do AppLibsList.$search(low($ref.libname)=low('swBase4'),1,0,1,0)
Do AppLibsList.$search(low($ref.libname)=low('swGui4'),1,0,1,0)
Do AppLibsList.$search(low($ref.libname)=low('swIcons4'),1,0,1,0)
Do AppLibsList.$search(low($ref.libname)=low('swRefs4'),1,0,1,0)
Do AppLibsList.$search(low($ref.libname)=low('swReports4'),1,0,1,0)

; Remove the non-selected libraries.
Do AppLibsList.$remove(kListKeepSelected)

Quit method AppLibsList

The above steps may already be setup in your application. You might just have to modify the $:AppLibsList method to suit your application.

Main Library Startup_Task

The main library Startup_Task is the control center of your StudioWorks application.

The key object classes (oConstants, oErrorHandler, oLogon,...) are instantiated by its task variables and available to the rest of the application's libraries.
The $construct method opens the modules folder libraries and the studiowork folder libraries, initializes the key object classes, opens the Sign-In window (or auto signs in), and installs the menus.
The $destruct method saves user settings, logs off the database, and closes the modules folder libraries.

When opening a StudioWorks application, the main library startup task $construct method has 2 important jobs to complete before anything can happen:

Open the studioworks folder libraries.

Without the StudioWorks core libraries we are missing the key object classes and any class which is subclassed from a StudioWorks library is missing its superclass.
Initialize the error handler object which is instantiated by the startup task variable, errhndlr.

StudioWorks code depends the error handler for logging and communicating errors to the user.

Once the StudioWorks libraries are open and the error handler has been initialized the rest of the code can execute normally.

The oOpenLibraries object class is used by the main library Startup_Task to open the StudioWorks core libraries. The oOpenLibraries object class must be copied from swBase4 to the main library.

There is a problem during startup with handling errors:

The oPaths object can not log errors to the error handler until the StudioWorks core libraries have been opened and the error handler has been initialized.
If the error handler hits an error when it is being initialized how does it report the error to the user?

One solution is to open an OK message to notify the user of the error. The problem with this solution is that if the application is being used as an Omnis web app, the OK message will halt the web server app. (not a good thing.)

The solution which we have opted for in StudioWorks is to send the error to the trace log and then open the trace log. This solution is only used for errors that occur during startup before the StudioWorks libraries are open and the error handler has been initialized.

Creating a Key Object Subclass

When you start a new StudioWorks application most of the main library Startup_Task task variables point to object classes in the you main library which are subclass from objects in the StudioWorks core libraries (swBase4, swGui4, swReports,...).

There comes a point in your StudioWorks application development where you will want to add or modify a method in one of the key objects. In order to do that you will need to override an existing method or add your own method to the subclass object in your main library. The following is an example for adding a custom method to the oFunctions object.

F2 Browser > select oFunctions in your main library > F8 Methods.
Add a $testMethod and put a 4GL Breakpoint command in the method.
Programmer Menu > Programmer Test Method... to get to the breakpoint.
Enter the following line of code in the Programmer Test Method

Do fn.$testMethod()
Double-click the line of code your entered and click the Step In toolbar button. You should now be inside the $testMethod of your subclass of oFunctions.

If you want to change a superclass method, do the following steps.

Override the superclass method in your subclass object.
Enter your own custom code. If possible, and it makes sense, you should begin your custom code with Do inherited returns FlagOK (or Returns Value). That way you still use the superclass method, and then add your own custom functionality to the superclass method.

; Sample code if the superclass returns true or false
Do inherited Returns FlagOK
If FlagOK
   ; Enter your custom code here

End If
Quit method FlagOK

; Sample code if the superclass returns a value
Do inherited Returns Value
If not(isnull(Value))
   ; Enter your custom code here

End If
Quit method Value