The First Run tab of the global support extension template is where you enable and configure the First Run technology.

 

First Run technology makes it possible for ProPath to determine if an application is being ran for the first time on a computer based on a "Trigger" event.

 

When the First Run condition is detected, ProPath can:

 

•Allow the user to pick a data path (or confirm one suggested from a CSIDL location)

•Create the data path folders

•Run another procedure of your choice (such as a program Setup procedure)

 

The First Run condition also sets a flag that you can check in the ProPath Global Embeds.  This allows you to insert code to do just about anything when the flag is set.

 

 

 

Enabling First Run

 

When the Enable First Run Technology box is checked, then the ProPath templates will generate code based on your selections.  If it is not checked then the template selections will be disabled and no related code will be generated.

 

 

The First Run Controller

 

When First Run is enabled, you will see an indicator of which one of the ProPath objects is doing the First Run detection as shown here:

 

PFF:MAINData is the ProPath class object for the MAIN data folder.

PFF:SYSTEMData is the ProPath class object for the SYSTEM data folder.

 

Note: If the SYSTEM Data Path is enabled then that object will automatically become the First Run Controller as it is the first ProPath class object to be initialized.

 

Important: the trigger options will change depending on your selections that tell ProPath where the data is stored.  Not all options are available with all combinations.

 

 

First Run Triggers

 

First run has different items that can be used to detect the First Run.  They are called "Triggers" and they are discussed here.

 

 

 

ProPath Modes

 

ProPath Modes are a simple numeric representation of the combination of MAIN and/or SYSTEM options that determine where data is stored.  There are a total of eight operational modes.

 

This screen shot shows the current ProPath Mode:

 

As you change settings on the MAIN and SYSTEM tab that tell ProPath where the data is stored, the Mode number will change.  This number is stored in a variable and is used to tell the Universal Path Selection procedure which tab to display.

 

 

 

User Path Control

 

In certain Modes, you have the possibility of allowing the user to confirm the path (or select a new one).  When one of those modes is set (based on your path control selections) you will see these fields enabled:

 

To use this feature you need to check the box that enables the feature and provide the name of a procedure to run.

 

Important Note: As shown on the template as a reminder, the procedures must be Declared Globally

 

 

Hint: The checkbox to declare a procedure globally is shown here:

 

 

 

The Universal Path Selection Procedure

 

To save time, you can use the Utility Template Wizard to import the ProPath Select Path procedure ( WnSelectPath ) into your application.

 

Information about and screen shots of  this procedure can be found here.

 

Details on importing the procedure and configuring it are found here.

 

Details on designing your own path select procedure can be found here.

 

 

 

Post First Run Procedure

 

ProPath also makes it possible for you to run your own custom procedure when the First Run event occurs.

 

Note: if you are using the WnSelectPath procedure (or one of your own design) to set the paths, then the Post First Run procedure would run AFTER the user had clicked Ok and saved a valid path.

 

This can be a useful way to set system options the first time your application is ran on a computer.

 

 

To use this feature, simply put the name of the procedure in the field provided.

 

Note: if the procedure is a MDI window then be sure to check the START this procedure box since ProPath will run your procedure before the Appframe starts

 

 

Also remember to check the box on your procedure that declares it globally.

 

 

In the example above, we are calling a FORM ( UpdateSettings )that updates a single record control file ( this is in Demo6.app ).

 

When the Demo6.app first runs the user sees this window to select or confirm the data paths:

 

 

Then this window is displayed after the user clicks Ok:

 

 

After entering the setup data, the program starts normally with the data paths fully initialized and user configuration data in place.

 

 

Since this was a MDI window the user can go into change the settings again from the pulldown menu as shown here:

 

 

Then the window opens normally as shown here:

 

 

 

First Run Reset

 

ProPath has another nice feature called First Run Reset.

 

This feature makes it possible for you to simulate the First Run condition at any time with a command line option to your application.

 

 

Enabling First Run Reset

 

To enable this feature simply check the box as shown above.  The default command line parameter is /FIRSTRUN, but you can change that if needed.

 

When your program is started with this parameter on the command line, then the class checks for the First Run condition will be bypassed and the path select procedure (as well as your Post First Run procedure) will be executed.

 

This can be a very useful feature for situations such as when a user physically moves the data folder (to a new machine or folder) and you need to reset the stored path so that it points to the correct location.

 

 

 

Testing First Run with SETCOMMAND

 

In order to be able to test your First Run code, ProPath has a developer option that you can check that uses the Clarion SETCOMMAND option to simulate a parameter on the command line.

 

All you need to do is check the box, recompile and run your program.

 

When the program starts with this option enabled you will see this message:

 

 

This message is put in place by the template to help prevent your accidentally shipping your program with the SETCOMMAND test enabled.