Vote for this Product at ClarionShop  
Buy now at ClarionShop
Version

www.capesoft.com
Updated Wednesday 24 December 2008 		c3pa approved
     

What's new in Secwin 4?



Documentation
  JumpStart User Guide  
Template Reference Technical Reference
Other Information  
     


Make sure you read this!
  Things you absolutely have to know before you start  
JumpStart Adding the Licensing and Registration features
JumpStart Adding Logins and Passwords
JumpStart Adding Screen and Control Access Control
What to Read Next
     


Contents: User Guide
 
Introduction to User Guide:
Access Control:
Licensing and Registration :

 
The Security File:
Customizing Look and Feel of the Secwin Windows:
Using SecWin in a NetTalk WebServer (coming soon)
Support:
Miscellaneous:
Advanced Programmer Functions:
Release History
 
     


Things you absolutely have to know before you start

Take a couple of minutes to read this section. It may cover some terms and ideas you already know, but it will save much frustration and heartache later.

Secwin is a mature Feature-Rich package. This means that the most common problem encountered by new users is Feature Overload. With so many features, and possibilities, it's hard to understand how to accomplish the simple tasks. Of course the features are there for a reason, and you'll appreciate them later, but for now they get in the way.

One way to overcome this problem is to check out the JumpStart section for task orientated documentation. For example you just want to add the Login features? No problem, check out the section on Adding Logins and Passwords. Just want to implement product Registration? Check out the Adding Licensing and Registration Features. (Not yet though read the rest of this section first!)

Secwin is divided into 2 halves. You can use either half separately, or the two together in an integrated system.
Secwin also makes extensive use of Templates in order to implement the features that you want. If you've been using Clarion for a while then you're already familiar with the power that templates offer. But if you haven't used a 3rd party template before then take a moment to read the QuickStart section entitled Using templates in Clarion. Secwin uses a mixture of Extension/Control and Code templates.

If you are supplying a program which needs translation then read the section entitled Translating Secwin Windows.

Secwin stores the security settings in a file called dssw4.TPS. This contains both the Access Control settings and the Licensing settings. Please note that in the case of the 30 day demo licensing feature, deleting the dssw4.TPS file does not allow you to get another 30 day license. For more information on this feature see the 30 Day Demo section in the Secwin User Guide.

Although Secwin contains a feature called Super Users, this is not a security back door. For a full explanation of the Super User features see the section in the User Guide called Super Users.

Important Note: The security files are not encrypted. The sensitive fields are encrypted, so that security is not an issue, but illegal write activity is possible. Secwin will detect when an illegal write activity has been made  to the security files, and will not allow the user to run the application. You need to keep regular backups so that the user can immediately roll back to a previous version of the security files and continue running your application.

[Each developer needs his own license to use Secwin. (Need to buy more licenses?) ]

Features included in Secwin4

Access Control:

Licencing and Registration Control:

Additional Features:

Note: in Secwin 4, all the File driver DLLs are included in the main install, so you will not require any additional install files for other driver support.

Why is Capesoft charging for an upgrade from Secwin 3 to Secwin 4?
How do I upgrade from Secwin 3 to Secwin 4?
What do we need to change in order to upgrade from Secwin3 to Secwin4?



JumpStart: Adding the Licensing and Registration Features

This is a quick way to get going implementing the Licensing and Registration features. It's by no means all the power available to you, but it's enough to get you up and running. we recommend reading the items in the Secwin User Guide related to Licensing and Registration for more information on what is available.

  1. Add Secwin's Activate Security Global extension to your Application.
    In the following template prompts of the Global Extension Template:
    a) Enter Unique Application Name.
    b) On the Licensing tab, uncheck the Disable Licensing support and enter the License Name and Seed Code. These should be unique for your app, but remember them we'll use them again later. You can ignore the other template prompts, these are superfluous at this stage.
    c) On the Files tab set the Allow Program to create Security Files on, and set the Position to Exe directory. If your application uses SQL, then see the Secwin Global Extension template for details on setting up an SQL connection for the Secwin tables. You can ignore the other template prompts, these are superfluous at this stage.
  2. In the Template utility item on the Application menu, Run the Template utility: CreateMyRegisterProductWindow. This will add a procedure to your application called SecwinRegisterProduct. If you're wanting to use Access Control, then run the template utility CreateAccessControlWindows now as well.
  3. On the Frame procedure add the User Screen Security extension template (if you have not already added it)
    In the following template prompts of the Global Extension Template:
    a) Click on the License Check and Restrictions button.
    b) On Levels Tab : Set level to Demo
    c) On Action Tab : Set action to Disable all controls except.
    d) Select controls which you want still to be available if the program has expired. These typically include, ?Exit, ?HelpAbout and ?RegisterProduct (which you'll add just now). Note that you also need to activate the menu name of these items if it exists (e.g. ?FileMenu). If your menu does not exist in the list, then you need to add a Use Variable to that Menu in the Menu Editor (in the Window Formatter)
  4. On the Frame procedure add the User Login Here extension template (if it's not already there.)
    For the Options on the Extension
    a) On the Login Options tab set the Unique Area Name to Main
    b) On the Login Options tab set the Make login optional to end user switch ON (if you are not wanting to use Access Control)
    c) Optionally set the Allow 30 day demo option On or Off...( on is usually recommended).
  5. Go to the Frame procedure and add the Create Secwin Menu. If you are not going to use Access Control in this application, check the Disable Access Control Items checkbox.
  6. Compile and run your application. Depending on your choice in 4c you may or may not see a "Your product has expired" warning straight away. i.e. If you set the Demo mode on then you're likely to get an instant 30 day demo license. If however you left the switch off then you will need to register your program at this point.
TIP : At this point a lot of developers get easily confused. You need to register your own program on your own computer. Any registration type error messages you get do not apply to Secwin itself, but rather illustrate that the Secwin features in your application are in fact working.

To register your product - which is what your client will need to do when, or before, it expires, use the supplied Register Application or use Secwin Online Server to supply activation codes on line.

The manual registration application is shipped as one of the Secwin examples, and can be modified to suit your needs. It can be found in the \clarion\3rdparty\examples\secwin\register directory.

In it's simplest form Register application allows you to capture:

TIP : For a full description of the Register example see the Secwin Examples Reference manual.
TIP : To the right of all alpha-numeric fields on the window is a Check number. This number will be visible to the client while typing the details in. If his number does not match the supplied number then a spelling mistake has occurred.
TIP : Read the sections in the User Guide which cover the Licensing and Registration features and options to learn more about what is, and isn't possible using the Registration features.



JumpStart: Adding Logins and Passwords

This is a quick way to get going implementing the Login and Password features. It's by no means all the power available to you, but it's enough to get you up and running. we recommend reading the items in the Secwin User Guide related to Licensing and Registration for more information on what is available.

1. Run the Create AccessControl windows template utility from the Application | Template Utility menu item in the Clarion IDE.
NOTE: If it's a legacy app, use the CreateaccesscontrolWindowsLegacy, and if it's an ABC app, use the CreateAccessControlWindowsABC.
This will add a number of Secwin windows to your application (you'll probably want to do this in your data dll in a Multi-DLL application). If you are wanting to use the Licencing and Registration part of Secwin, then run the CreateMyRegisterProductWindow template utility now as well. If you don't get the windows, then you're using the wrong template utility.

2. Add Secwin's Activate Security Global extension to your Application.
For the Options on the Extension
a) Enter Unique Application Name. For Multi-DLL applications, read up on the Using Secwin In MultiDLL Apps section of the docs.
b) On the Files tab set the Allow Program to create Security Files on, and set the Position to Exe directory.

Tip : This method of creating files is not very secure if you aren't using the licensing features. If you aren't using licensing then read about Creating the Security File soon. For now though continue the QuickStart.

c) On the Options tab, set the Function Overrides as follows:

 

Note: SetAccess must be set to SecwinSetAccess NOT SecwinSetAllAccess.

Note: For Multi-DLL users, you'll want to compile the data DLL now, and then switch over to your main exe at this point. Repeat steps 1 and 2 in the EXE application. In step 1, make sure you check the 'Import the procedures as external' checkbox on the template utility.

3. Go to the Frame, or Main Menu, procedure. Add Secwin's User Login Here Extension template (if it's not there already).
For the Options on the Extension
a) On the General tab, set the Unique Area Name as Main.
b) If you don't want AccessControl to be optional for the end user, then make sure that the Make Login Optional to End User is unchecked.

4. Continuing in the Frame procedure, add Secwin's Create Secwin Menu extension template. If it was already there, then make sure that the Disable Access Control Items checkbox is unchecked, and that the following procedures are set correctly:

The first time the program is run you will be asked to add the first user. A User's information is made up of a First Name, Last Name and Login code. When you add a user the the password is automatically set to be the same as the Login code. After you have finished entering the first user, then you can use the Login code, and Password (which will be the same at this point) to log in.

After you have logged in you can add more users using the Browse Users item in the Security menu created by the Create Secwin Menu extension template. You can also change your own password using the Change Password item created by the Create Secwin Menu extension template.

TIP : We get lots of questions about passwords. For most of the answers see the section in the Secwin User Guide entitled Logins and Passwords.



JumpStart: Adding Screen, and Control, Access Control

It's unlikely that you'll limit your access control features to just a login. You'll also want your customers to be able to control who goes where, and does what. this section is designed to follow on from the Adding Logins and Passwords section, so if you haven't done that, then do that now. Which is why this section is also in the QuickStart.

The User Screen Security template allows you to protect any window in your application, and also to protect individual controls on that window. Actually the template also checks the licensing settings for that screen, but those features are discussed in the section called Adding the Licensing and Registration features.

To Add the extension to your application simply go to the procedure you want to protect, Click on Extensions, Insert and select User Screen Security from the list. the procedure has 4 basic options;

a) Screen Name : Leave this blank and the procedure name will be used.
b) License Check and Restrictions Button : This controls all the license requirements for this window.
c) This procedure doesn't have a window : this is used when you add this extension to a report (usually for Licensing reasons).
d) Disable Screen Security here : Allows you to disable this template without losing all of the options you've set.
e) Control Restrictions Button : This is the place to set the screen security restrictions.

When you press the Control Restrictions Button you'll see a list of protected controls (which is probably blank to begin with). Click on Insert to protect a control. This is possible the most complicated bit, it's where you set which controls you want to protect, and so on.

Unique Bit Position : This is simply a number from 1 to 252. Start from 1 and avoid, if you can, missing any numbers out. It's not too serious if you do. DON'T move items around once you've started shipping your program.

Name : This is a name for the column on the Set Access Screen. Use a simple name, like for the Delete button use Delete, for the Print button use Print and so on. This name is limited to 7 characters long, so use something short.

Use Equate : This is the Equate for the control you want to protect. Select it from the drop-down list.

List box Column : If the control is a list box, then you can protect an individual column in the list box if you like. For example you might just want to suppress the Salaries column. If so, enter the Column Number here.

Action : This determines what should happen when the user does not have access to a field. Button controls are typically disabled (Menu Items MUST be Disabled, not hidden). Entry Fields are often hidden. However the action is up to you.

Attach Other Controls : In some cases you want a group of controls to be set, and unset, together. In this case click on this button and you can add as many controls as you like. Ultimately if the user has access to one of the controls then he'll have access to them all. This appears as a single setting on the user's screen.

Repeat this procedure for all the windows that you want to protect. I know this sounds like a lot of work, and it may be a couple of hours worth the first time you do it, but it's much easier than writing the code, and gives you full control over what's being set.

What to Read Next

Ok, you've got this far, but we've only just scratched the surface. You're up and running, but there're lots of features you could still use, and maybe you even have a question or three. Probably the next bit to read is the Secwin User Guide - this explains the different features at a concept, and implementation level, so you can decide which ones you want to implement.

You've also probably noticed a lot of possibly exciting template switches in your Secwin use so far - if you want to know more about what each switch does then check out the Secwin Template Reference.

If you really want to start exercising some power, then check out the Secwin Technical Reference. This contains descriptions of all the Secwin functions available to you.

Of course if these docs don't explain something clearly enough - or if you need a question answered then don't hesitate to contact support@capesoft.com - we're there to answer your questions.


 
User Guide
Access Control Features Licensing Features Other Features
Overview of Access Control Overview of Licensing Creating the Security File
Logins and Password Access Control Some Activation Code Secrets Locating the Security File
Operator Browse and Form Branding on Reports Security-File Driver
Screen Security Access Control Branding Using Logo Screens Changing the Logo
Set Access Rights Screen Hardware Copy Protection Making your own Secwin Windows
Ancillary User Functions Using Levels Secwin Error Messages
User Groups Automatic Temporary Licenses Using Secwin in Multi-DLL Apps
Work Groups Using Optional Modules Converting from Secwin 2.x
Bypassing Access Control Using Network Copies Secwin Examples
  Using Expiry Dates Super Users
  Using Counters Translating Secwin Windows
  When the License Fails Pin Numbers
    Advanced Programmer Functions
    CapeSoft Makeover Compatability
    ClarioNet / WebBuilder Compatibility
    IP Driver Compatibility




Access Control

Overview of Access Control Features

Access Control features allow the user to limit access to his application based on who is using the program. This is necessary in many database applications where you wish to expose some of the users to more data than others.

The primary feature for all Access control is Logins and Passwords. This allows the computer to determine who is using the program, and is essential for all the other features to work. For a complete explanation and details on how to implement see the section called Login and Password Access Control.

The next most common features is being able to limit access to screens, and controls, within your application. This is taken care of using the Screen Security template which is discussed in the section called Screen Security Access Control.

The flip side of implementing all this access control, is how the end user goes about managing it. Read about this in the sections called Operator Browse and Form screen, and the Set Access Rights screen.

Ancillary User Functions, like Change Password, Change Login and Lock Screen are also helpful at this point.

User Groups are useful for grouping users together. This can simplify the setting of user's access rights at runtime.

Work Groups are useful for programmatic limiting of users. In other words by using the Workgroup field you can group users together and limit their rights in your own way.

Advanced Programmer Functions describes some of the functions available to the programmer for doing their own advanced functionality.

If you're not wanting Access Control, but just wanting to use the Licensing and Registration part of Secwin, then take a look at the Bypassing Access Control section.

Login and Password Access Control

The basis of Access Control is the concept of each user having their own Login and Password. In it's most basic form Secwin allows you to protect a program simply by requiring a valid Login and Password before it will run. This is described in the QuickStart section Adding Logins and Passwords. Not surprisingly though even a function as simple as this can have some quite complicated options.

Security will always be a balancing act. The opposite of security is convenience, foolproof security is almost impossibly inconvenient, while simplifying it almost always leads to lower levels of security. With Secwin you can set very tight security, but unless it's absolutely required, your users won't thank you for it. One of your first jobs is to determine how tight the security needs to be, and implement it appropriately.

Most of the options when it comes to the Login screen, apply to the password. these options can all be set on the User Login here template and include things like minimum strength passwords, case sensitivity, and frequent password change enforcement.

Lost a password? The password itself is not available to either the programmer, or any other user in the system. Because Secwin has been designed to span across applications, and networks, it would constitute a major security flaw for one user to be able to find out the password for another user. This means effectively, that if a password is forgotten, there is no way to retrieve it. If the password can't be remembered, then the user will have to be deleted and re-added. ( Tip : You can use User Groups to handle folk who are continually forgetting passwords. See the section in the User Guide entitled User Groups.)

Alternatively, take a look at Using an encryption key for details on an alternative method of access control, which enables you to retrieve the password.

You can choose to password protect an entire program with one login and password (by far the most common approach), or divide the program into multiple areas, each area having its own login screen. In the case of multiple logins the same user would use the same user code and password for all the areas. however they may not be granted access to all the areas, and their status from one area to another can change.

Multiple applications using Secwin, and sharing a common dssw4.TPS file, will share a common list of users and passwords. Thus a user has the same login code and password to all the EXEs that he has access to. If he changes his password in one place, then it will change for all his logins.

TIP : If you have a Multiple-Exe product, then you can consider each Application to be it's own area. However it is possible for all the EXEs to have the same Area definition, and hence have the same access rights apply to all the EXEs. This is done by setting the Unique Application Name (on the Secwin Global Extension) and the Unique Area Name (on the Secwin User Login Here Extension) to be the same across all the Applications.

Advanced : Although it is most common to have the first Login screen appear when the Application starts, it is possible to leave the Frame procedure, and some of the sub-ordinate procedures unprotected, and just require a login when a certain procedure is run, for example a Report, or System Settings procedure. This is done by removing the Login extension from the frame, and adding it to the procedures where you do want the users to Login.

Definitions:

When a user logs in they can be classified into one of 3 possible Levels. 

Supervisor: This level has all the power - the supervisor has access to the whole application (or area) - and has the power to add users and user groups and limit those users and groups. 
No Access: This Level has no power (in fact they will be denied access). These users will not appear in the list of operators that the SuperVisor can assign access to (for security areas in the application).
Operator: This level is in between - he does not have the power to add or update users, or their access points, but he is in the list of operators that the supervisor can grant or deny access to (areas of) the application.

The difference between a Supervisor, and an Operator is obviously a significant one. Simply put, a Supervisor is allowed to change the security access rights of other Users. An Operator can not change either their own, or anyone else's, Access rights.

Each Operator can be assign an initial access of either All Access or No Access. This is the default access for any particular security access point in your application for that operator. The Supervisor can change that default access to any of the security points. An operator with an initial access of No Access will need to be assigned access by the supervisor before they will have access to a security area.

Note: The difference between a user that is an operator with an initial access of No Access and a user that has a level of No Access, is that the supervisor will be able to grant access to the operator to particular areas of the program, but the No Access user will not appear on the list of users that the supervisor can give access to. The supervisor must change a No Access user to an operator if they are to be given access into your application.

Operator Browse and Form Screens

The Operator Browse and Form screens are used to manage the user list for the program. They're also able to group users together (into User Groups) but that is discussed in a section called User Groups.

The Operator Browse screen should be on your Application's main menu - as described in Step (3) of the QuickStart section called Adding Logins and Passwords.

Any Supervisor can add new Users using these built-in Operator Browse and Form Screens. On the Form are the following fields;

First name & Last name : These apply obviously to the operator.

Login : This is the Login Code the user will use to identify himself to the system. Note that the supervisor cannot set the password for the user. The password will default to be the same as the Login Code, after that only the user can change it. Note: The login cannot be purely numeric. It must contain at least one alpha character (see the ds_GetProperty function reference).

Level : Set the User to be either another Supervisor, and Operator, or a User with No Access to this Area.

Default Access : If the User is an Operator, then you can set their Default Access. this is typically either All Access, or No Access, but it can also be set to the Login code of another Operator. In that case the new operator will assume all the current Screen Security settings of the selected Default Access operator. Note that this will only be for this application name (set in the Secwin Global Extension template) - not across every application that uses that dssw4.tps file. (See Definitions for more details)

User Group : If the User is an Operator, then he can belong to any number of pre-defined User Groups. For complete information on what User Groups are, read the section in this guide entitled User Groups.

Workgroup : You can assign a Workgroup number to the user. For more information on Work Groups, see the section in this guide entitled Work Groups.

TIP : For programmatic access to the Users list see the ds_InsertUserEx , ds_ChangeUser, ds_DeleteUser and ds_UsersEx functions in the Secwin Technical Reference.

Screen Security Access Control

The Screen Security Access Control is handled by a template called User Screen Security. This is added to each procedure where you want it. See the QuickStart section called Adding Screen, and Control, Access Control.

Wherever this extension is added, the end user will be able to set his own security using the Set Access Rights screen.

Set Access Rights Screen

While the Operator Browse screen lets you set access rights to the whole program, The Set Access screen allows the end user to limit access to specific controls, and windows within the application.

The main goal here is simplicity. The idea is that your customer must be able to work this screen, regardless of their computer skills, and you must be able to teach it to them in a quick and simple way. To this end we have avoided the use of complicated windows which allow you to set multiple settings at the same time.

The screens, and controls, that support this feature are set by the programmer at compile time, but the actual access rights are set by the end-user when he runs the program. As the programmer you can find out how to activate the security by reading the section called Screen Security Access Control. In this section we'll concentrate on how the end-user uses that security.

In order to set security rights the end-user must be logged in as a supervisor.

By going to any window with the User Screen Security extension, and pressing Ctrl-F8, they will get the Set Access window. This window will have a list of the Operators on one side (Users with No Access, and Supervisors are not listed). User Groups will also be listed, and users already assigned to groups are not listed.

The list takes the form of a spreadsheet, with the names on the left, and the access rights on the right. By simply double-clicking on the displayed rights, access can be changed from Yes to No. Closing the screen is done by clicking on the Close button.

So if the user wishes to stop users Deleting his Customers, then simply by going to the Customer Browse, and pressing Ctrl-F8, he can limit the access to the Delete button.

Note: You can make use of the Secwin Global SetAccess window as well, which makes setting access points much easier than using the SetAccess screen.

Ancillary User Functions

These functions are designed to be added to your program as features for your end-user to use. The first one Change Password is likely a necessity, while the other 2 Change Login, and Lock Screen are optional.

Change Password : This allows your end user to change his password. He will need to enter both the old password and the new password. On your login extension template you are able to set minimum password requirements (Force Password Change - Force Long Password). You can also make your own Change Password screen, see the section entitled Making Your Own Secwin Windows. To use the built-in Secwin Change Password window see the Change Password Code template.

See FAQ3.4 for details on how to retrieve lost passwords.

Change Login : This function allows the users to change from one user to another without exiting the program. You can make your own Change Login screen, see the Making your Own Secwin Windows section for details. To change the Login using the build-in Secwin Change Login screen see the Change Login Code template.

Lock Screen : This blanks out the screen so that others can't see it. Only necessary in specific situations. Note that this does not protect the whole machine, only the running application. The user is required to re-enter their password before continuing. To call the Lock Screen function use the Lock Screen Code template.

User Groups

If you have a large number of users then it may not be convenient to set the access rights for all the users individually. In this case you can create groups of users, cunningly called User Groups.

To create a User Group use the Operator Browse screen, and User Group Details button.

To put users into groups use the Operator's Form. A List of User Groups is provided that the user may be allocated to. In Secwin 4 the User may be allocated to multiple UserGroups. Note that this list box will only be available if the User is set to be an Operator.

Setting the rights for a Group is exactly the same as setting for an individual. Simply use the Set Access screen while the program is running.

Note: an Operator can now be part of more than one User Group.

Tip : When you create a new user or user group, you can set it to have an existing user or user group's access rights (when it's created). You can diverge the two groups (i.e. if you wanted more options for the one than the other).
Tip : If a user is always forgetting their password, and you get tired of resetting their access rights every time you have to delete, and re-add them, then make a user group for that person. The access rights will be stored with the Group, not the User, so it's easier to delete, and re-add the user.

What happens about access rights when a user gets added to a usergroup:

When a user is assigned to a user group he loses his individual access rights and only takes on those of the user group. If he joins multiple user group, then his access is an "or" function of the user group's rights. For example: one user group is denied access to a particular screen and another is allowed access, and the user belongs to both user group, he will be allowed access.

Work Groups

Work Groups are different to User Groups, they require more effort from the programmer (you need to handcode where access is limited to a workgroup, or where a user is limited by belonging to a workgroup) - and can be confusing to the end user. The difference between User Groups and Work Groups is that user groups' access are runtime assignable - whereas workgroups' access is programmed into your application. A user is assigned to a workgroup at runtime (hence the confusion on the supervisor's part of where the access points are), even though the access points are set at compile time.

They are essentially a number (a long) which you can store with each user.

This number can be used to limit browse records which are available, or it may be used to perform some specific access control feature of your own.

The Work Group number, for each user, is set on the normal Operator Form. Each operator can only belong to one workgroup.

Example:

If ds_GetProperty(AppNum,,'WorkGroup') = 2
  !Allow user into this routine
end

So to summarize: In order to use a WorkGroup for an operator, you need to programmatically set the access rights in your application (for the area that you want to limit access to), and then at runtime, assign that operator to the WorkGroup Number you used in code.

 

Bypassing Access Control

There're a couple of reasons why you may like to bypass the Access control part of Secwin (a bit like disabling Access Control - but technically it's working around it). The primary reason for doing this, is for demo purposes - i.e. you want your program to run without forcing the user to login. Alternatively, you may not require Access control for your program period, you might like to just use the Licencing and Registration features.

There're 2 ways of Bypassing Access Control this:

1. Check the Make Login Optional to End User (on the User_Login template - Login Options tab). You won't need to ship a dssw4.tps file (although you can if you want to use Access Control later). This means that access control is bypassed. This is typically for people you don't require Access Control or would like to make access control optional.
2. Check the Allow default login values (on the User_Login template - Login Options tab) use a default Login code and password and ship a dssw4.tps file that contains the default user (if you want access control at a later stage, but not in the demo application). This is typically for people who require access control (either now or at a later stage), but not in the demo application.

Note: When shipping a dssw4.tps file, you need to make sure that dssw4.tps file does not overwrite the one that already exists there (for people downloading a program update who have already set up all their user settings). 

Multi-DLL Applications

When you add an operator and set his default access to 'All Access', this will only be for the application that he is added to. For other applications, his default access is set to 'No Access'. This is because it would pose a major security flaw if you could create a user in a Secwin enabled application and get all access rights to a completely unrelated application. In order to allow cross-pollination of operators in a Multi-DLL environment (IOW across multiple apps which are essentially the same application) - you need to set the app name the same for each application (you need to do this in the Secwin Global Extension template). See the Definitions section of this doc for more details.


Licensing and Registration

Overview of Licensing Features

The basic goal of the licensing features is allow you to sell your program in different flavors, and yet have a single set of install files. In other words by making use of an Activation Code, you can limit, or extend, your program based on the amount that the client pays. You can use all the licensing features, or more likely, you'll just make use of a few of them. In this User Guide each feature will be discussed in more detail, so take a moment to read though them and decide which ones you want to use. These features include;

Product Branding through the use of the user's company name, and a serial number. this means you advertise on your screens, and on your reports, the name of the licensed user. This makes it difficult for illegal user to distribute reports etc. For more information read Branding on Reports, and Branding using Logo Screens.

Levels allow you to enable a piece of your program, then a bit more, then a bit more, and so on. Each Level is a superset of the previous levels - in other words each level includes all of the previous level's features. By default these levels are named (in order) Demo, Lite, Standard, Professional and Enterprise, however you can name them anything you like. See Using Levels for more details on this feature.

Automatic Demo Licenses allow you to distribute demo versions of your program that run only for 30 days. Please note that this feature is very 'strong', so testing is difficult. Read Automatic Demo Licenses for more information.

Optional Modules allow you to activate up to 30 separate, unrelated, modules, in addition to your main program. For example in accounting applications you often purchase a combination of modules - General Ledger, Debtors Ledger and so on. See Using Optional Modules for details on this feature.

Concurrent Network Copies allows you to limit the number of simultaneous, concurrent, users on a network. The user can load your program on any number of computers, but only a limited number of users will be able to access the data at any one time. See Using Network Copies.

Users currently logged in. This feature is something of a bonus that you get when you implement licensing in your program. Because of the concurrent network copies feature, Secwin is able to track who is currently logged into your program. This can be very useful for network updates, as you can ask users to quit the system while you upgrade the program. See Using Network Copies.

Expiry Dates allows you to control when the program will cease working. This can be used for distributing 30 day demo versions of your software, or for licensing your software for limited periods of time (for example yearly license renewals.) See Using Expiry Dates for the specifics.

Counters are somewhat less common. Essentially they allow you to sell your program based on the number of times it will be run, or the number of reports that will be printed, or something like that. Alternatively you might use it just to store an extra number which you want to use somewhere in your program. See Using Counters.

All of the features are activated and de-activated through an Activation Code. This code is generated by you, using either the Register example application or using an online activation code generator (like Secwin Online Server).

If the user doesn't have sufficient access then the License will fail. The exact action taken when this happens is determined by you - see the section called When the License Fails.

Some Activation Code secrets

Activation codes contain the date on which they were generated, and you can specify the life length of the activation code. By limiting the period that the activation code is valid, you can limit activation codes being passed around and used by many users over an extended period of time. Don't get confused between this date and the Licence Expiry date though, these are 2 completely separate features.

This code should be written into your application that generates registration codes. There is a default registry code generation app that ships with SecWin as an example (3rdparty\examples\secwin\register\register.app), which you can modify to suit your needs.

Branding

Branding on Reports

An effective, and non-intrusive (to the registered user), form of copy protection is Product Branding. One technique you use for Product Branding is to put the name of the Company that registered the software on the reports.

Unfortunately given the large number of report templates available, and the fact that most reports are heavily customized, if not hand-written, it's not possible to write an Extension Template that will work in all situations. There is however a simple Code template, called Code : Call CurrentLicense, which will do most of the work for you. You can find details about the template here.

Branding using Logo Screens

One of the ways of Branding your product is to put the Licensed name of the user on the screen as a background to your Frame.

As you may know, it's not possible to put any controls in the 'Window' part of a Frame procedure. The best you can do is apply a bitmap graphic as the wallpaper to the window. As we want the background to be dynamic (to include the licensed user's name) a bitmap wallpaper isn't going to be good enough.

Secwin overcomes this limitation by allowing you to create a separate window procedure, put whatever you like in the window, and make this window the 'background' to the window part of the frame.

You use the normal Clarion Window template to create the window. You can put pretty much anything you like on the window - I often use the product name, and maybe a product logo here. Of course the most important thing to put here is the name of the current License holder. Note this is not the name of the user (although you could put that here as well if you like), but rather the name of the Company which has licensed the program.

There is one requirement for the window -it must have the MDI attribute turned on. If you don't do this, instead of the window being at the back, behind all your browses and forms, it will float to the front.

Some other suggestions which make the window work well are;

1. Set the position to 'center'.
2. Turn the Clarion feature to 'Save and Restore the Window position' off.
3. Remove the Caption, and the System Menu attribute.
4. Set the 'border' of the Window to 'None'.

The second requirement is to add the Secwin Extension template, called Extension : Make Logo Screen, to the window. This adds the code necessary to make it a background window. You can read more about the template, how to add it, and the options it has, here.

The last step is to add code to your program that Starts the Logo screen. Of course there is a Secwin template to do this as well, it's called the Extension : Run Logo Screen template, and you can read more about it here. This template is added to the Frame procedure itself.

See the Examples section for an example of this.

Hardware Copy Protection

In some cases you may want to 'lock' a particular activation code against the actual machine. There are a number of different hardware IDs that you might like to use - all of which have their weaknesses. You can use the ds_GetDriveSerialNumber to return the serial number of the hard disk (although some manufacturers are not particular astute at generating unique serial numbers). Alternatively you could obtain the MACAddress of the PC - although this could change as additional MACAddresses are added (in the form of extra network cards or virtual networks like Hamachi or Sonicwall). Although this number can be changed by the end user, given the correct tools, it is a reasonably effective way of ensuring that the data is not moved from one machine to another.

Tip : Many users upgrade their computers every 2 years or so. Network administrators change network drives more often then that. Each time the hard disk is changed the user will have to get a new activation code from you. If you're expecting a large number of installations then DO NOT use this feature. Use only in very select situations.

To implement a test based on this check, add the following code anywhere in your program, After the user has logged in;

if ds_CurrentSerialNumber() <> ds_GetDriveSerialNumber()
  ! oh dear - pirate code goes here....
end

Typically you would also display this number on your about screen. That way, when issuing the code, you know what to set the Serial Number to.  In other words the user needs to report to you his serial number (he shouldn't know it's the same as his hard disk) so you can generate a code which matches that number. 

When issuing the activation code (if you're not using Secwin Online Server) - you will need to add this hardware ID to one of the additional strings in the licence information:



In your SecwinRegisterProduct window, enter the following code in the Drop event for the XML drop region:

SecLoc:xmlFile = DropID()
Do ImportXMLFile
if SecLoc:AdditionalString1 = FunctionToGetID() !This could be ds_GetDriveSerialNumber
  post(event:accepted,?Sec:RegisterButton)
else
  disable(?Sec:RegisterButton)
    !Warn on mismatched ID here
  post(event:closewindow)
end

You also need to turn off the Automatically register when an XML file is dropped checkbox (on the RegisterProduct control template on the SecwinRegisterProduct window).

When loading the application you need to test the hardware to a saved licence:

LicenceDetails  group(ProductDetailsGroupType),pre(LD) .

  code
    LicenceDetails = ds_CurrentLicenceDetails()
    if LD:AdditionalString1 = FunctionToGetID()
    else
      !Invalid hardware for registered licence code.
    end


Using Levels

It's common these days to find different Levels available for the same program. For example a program with Lite in the name normally means there's a (more expensive) version, with more features, available. Another common feature is to distribute a free demo version which is limited either by time, or by feature set. ( The time option is discussed in the section entitled Using Expiry Dates).

Secwin supports up to 5 levels of the same program, although obviously you may not have need for all 5. The levels are named (by default) Demo, Lite, Standard, Professional and Enterprise. (You're free to rename the levels to anything you like). The idea is that each level is a superset of the previous one, with more features added. In other words the Lite level includes all the Demo features, and the Standard level includes the Demo, and Lite features and so on.

Using the User Screen Security Template you can set any of your procedures so that they require a specific level before they'll operate. For example you might set a procedure to require Level Lite - in which case it won't work in Demo mode. Or another procedure might require Level Professional, in which case it won't work in Demo, Lite or Standard Levels.

If you have a procedure where you want to use a Level restriction, then add the Screen Security extension to the procedure, click on the License Check and Restrictions button, and select the Level you require on the Levels tab.

Automatic Temporary Licenses

When the user runs your program on his machine for the first time you can set your application up that he can automatically get a temporary license for running your program. You can switch on this feature by going to the User Login Here template, on the Licensing tab, and turning on the Issue temporary licence when first run? switch. The length of the demo is set in the next option called Valid for (days). You can set the automatic license level in the Level drop down list.



This feature also cause much grief to Secwin developers because they find it difficult to test. Secwin will only issue ONE demo license for your program on any one machine. If the user registers the program then they will not get a 30 day temporary activation at any time after that. Also if they install your program, and get their temporary license, they will never get another for your program.

Automatic temporary licenses are issued with all modules enabled (see Using Optional Modules for more details on modules).

Tip 1 : Deleting the Security File (dssw4.Tps) is not sufficient to overcome this feature, so please don't complain when you can't make it work on your development machine a second time.

Tip 2 : If during the 30 day period, the PC date goes backwards, then the license will automatically, immediately, expire.

Using Optional Modules

Optional Modules are a lot like Levels, but while Levels work by each level including the previous level, Optional Modules work as completely separate units. The most common example of this approach is the Accounting Suite, where you can purchase any combination of General Ledger, Debtors Leger, Creditors Ledger, Payroll, Stock Control and so on.

When you issue an activation code, you can enable, or disable, up to 30 optional modules. Within your program you can use the User Screen Security extension to set any of your procedures to require one, or more, optional modules. You set the Modules require by going to the License Check and restrictions bottom, to the Modules tab.

Using Network Copies

One of the settings you can set when setting an Activation Code is the number of concurrent copies of your program that can be running at any one time.

The idea is that, in a network situation, it's a good idea to activate the program on as many machines as possible. By exposing more of the users to your program, ultimately means more money for you. So you load your program onto any number of workstations, but use Secwin to limit the number of concurrent connections that can be made to the data.

Using Network copies is very easy. Go to the User Login Here Extension, to the Licensing tab. Set the Licensing to be active, and set the Unique 4 Character License code. If you wish to turn off this feature then check the Disable Network Licensing switch. The number of copies that a user can have at one time is set as part of the Activation Code.

Secwin will use these 4 characters, plus a 4 digit number, to create a number of LIC files in your data directory. Each user as he logs in, will open one of these files using a Read/Write Deny Write file setting. For the duration, while he is logged in, this file will be locked. If your program GPFs, or the workstation is rebooted then the server will automatically unlock the file.

You can see a list of who's logged in by making a call to the ds_CurrentlyLoggedInEx function.

Note: This feature is only available currently for ISAM file users (using TPS, BTrieve, Clarion, etc file systems). SQL users will need to build in a TCP/IP client/server system to verify with other applications whether the number of current instances exceeds the permitted Network Copies. This is outside the scope of Secwin and requires a template such as NetTalk to implement this functionality.

Using Expiry Dates

This is the only option which is not actually set by the user on the Product Registration screen. This is because you may not actually want your end user to know there is an expiry date. The date itself is set when you generate the Activation Code. When the user's PC goes past this date, then the license will fail.

If the user sets the date back to the last date of the license, runs you program and then resets the date, then it is possible to bypass the Secwin date checking. Probably the best solution in this case would be to put a timer on the frame that checks the date is before the expiry date every few seconds, and shuts the program down as soon as the date goes past the expiry date. The function to call is ds_CurrentExpiryDate

If the user is really desperate, and resets the date in order to keep your program running (and keeps the PC date reset), then you could build a system that checks an internet date (you could use NetTalk to do this) and if the difference is > 1 day, then force the PC date to that date, and redo the license check. They would need to be connected to the internet at the time of the check though, so it might only take a short time for them to figure out the check is in place. What you could do is do the check once on startup - if there is no internet connection, then retrying every 30 seconds or so until one is established and you can then check the date. Of course, the user could always disconnect from the internet while they run your program - but eventually it gets so inconvenient for the user, that they eventually purchase an extended license.

Using Counters

Counters are probably the most unusual of the Secwin features. Typically they allow you to restrict the number of entries into a table, or to restrict your program based on the number of times a procedure has run (reports, or a procedure).

The counters for your client, are set when you issue the activation code.

Table Restrictions: 

For table restrictions, you need to:

  1. Add the table to be restricted in your Secwin Global Extension templates (on the Licensing tab).



    You can specify the table, the licence level range that the limit applies to. Levels below the limit will not allow any records, and licenses above the MaxLevel limit will not apply any limits to the table. The Default limit is the limit that is applied for a Default temporary initial activation licence - as well as what is initially set in the manual registration screen (if you are not using Secwin Online Server to automatically issue activation codes).

    What this will do is add a callback when an insert to the table is attempted and check the licensed limit for that table to verify that table limit has not yet been achieved. If so, then the insert will fail.
     
  2. In order to avoid the user from entering all the details on a form, and the insert only failing when the hit the OK button at the end of the form, you can add the User Screen Security template to your forms (for that table) - and check the Warn before insert if records are on the limit checkbox and specify the table to check in the drop down below that.

Procedural Restrictions:

In your program you can specify, using the Screen Security extension template, that a procedure Decrements the counter. When the counter reaches 0 then any procedure trying to decrement the counter will result in a License fail.

This could be used when your program is being evaluated, for example when you want to allow the user a fixed number of program runs before they have to purchase.

Alternatively it's possible to sell your program based on the number of times it is used. For example data applications can be sold by the number of reports that can be generated. You user can buy 10 reports, when they run out you simply issue another activation code, and they get 10 more.

To set a procedure to decrement a counter, go to the User Screen Security extension for that procedure, click on the License Check and Restrictions button, go to the Counter tab, and select the option Decrement Counter here. You need to specify which counter Secwin must decrement by a label (which must match the label of the counter in the registration window as well as that in the registration program issuing the activation code). This means that there is technically no limit to the number of counters your application can make use of.

It is also possible to deduct multiple "credits" from the counter field at one time. Use the ds_DecrementCounterEx function to do this.

For Secwin3 upgrade users:

If you made use of the counter in Secwin3, then the counter to resume using is the 'Default Counter'. If you need additional counters, then you can either make use of the Table Restrictions limit functionality, or else you can use other labels and add additional procedural counters to your registration window.

Using Serial Numbers

The Serial Number field is a string field which you are able to use for Serial Number purposes. It is not required for licensing purposes - but is provided for your convenience. You can use the Company name to make the license unique.

When the License Fails

Whenever the user accesses a procedure, and the users' current license doesn't meet the requirements for that procedure, then the license fails. You can decide on the action which must be taken at this point. The action is set on the User Screen Security template. Go to the License Check and Restrictions button, and go to the Actions tab.

The first option, and the most common action, is to display a warning message, and to close the procedure. Typically the procedure will close without any screen being opened, so the user will just see a warning message.

Alternatively you can set it to close immediately without the warning message.

You can also select for the procedure to carry on as normal, but for all the controls on the window to be disabled. Actually you can also override the disabling and allow some of the controls to be enables. This option is most often used on the Frame procedure. If the program starts, and the license fails (maybe it has expired) then you still want the user to access menu items like, Help About, Register Product, and File Exit. By using this option, and specifying these controls, the user will be able to get your information (from the About screen) and use the Register Product screen to enter a new Activation Code.

The final option is for it to call a procedure. This would most often be used when you have created your own product registration screen, and if the license on the FRAME procedure fails, you want it to automatically go to your procedure.
 

Including additional fields in the Licence

In Secwin4 you have the ability to use additional fields in the licence. The licence details group contains Other2, Other3, OtherLong, ExtraLong and ExtraString additional user-definable fields that you can make use of for additional parameters.

In your RegisterProduct window (check the Creating the Register Product section of the docs, if you have not created the SecwinRegisterProduct window in your application yet) you can add an additional field (up to 5 - 2 longs and 3 strings) for the additional items you would like to store.

These additional fields come already on the SecwinRegisterProduct window, but by default are hidden. You can unhide the Additional fields group, and then hide the controls that you don't require (unless you require all 5 additional fields). You can edit the field prompts to be something descriptive, and make sure that the Additional fields are populated on both the Register application (or Secwin Online Server) - as well as in your application when registering the licence, otherwise the activation code will not work.

Note: If you're using the built in xml file mechanism to transfer the licence details in an xml file, then you will not need to do anything extra to support this.

Using an XML file to transfer the licence details

By far the easiest way to transfer a licence details manually is via an XML file. This removes all possible user-entry error and makes it very simple for the user to enter licence details. Simply send them an email, include the XML file, and they can drag the xml file and drop it straight onto the RegisterProduct window in order to register the product.

You will need to create the xml file in your registration application. For an example of this, take a look at the RegisterABC application, in your Secwin Examples folder. This does not include a method of transporting the application, but using a product like NetTalk, will make emailing the XML file as an attachment very straight forward.

What you need to change in your application:

Nothing - except Creating the Register Product window in your application. Once this is accomplished, you will notice the following region on the SecwinRegisterProduct window:


 

Dropping the xml license file onto this region will automatically populate all the fields with the correct licence values. The user then simply has to click the register button and he's done.

If you want to support manual entry into the Register Product window as well as via the XML file (manual is by default disabled) - then you can do this by enabling the ?Sheet1 control in the Window Formatter of the Secwin_RegisterProduct window that you imported into your application.

Using Different Licence Types

Secwin supports different licence types (at this stage there are 2 types - Permanent and Temporary).  This feature enables your existing users to try out certain additional functionality for a demo period, without losing their Permanent Licence. Once a Permanent licence is issued, the Licence will always fall back to that permanent licence (after an issued temporary licence expires).

You can issue as many temporary codes as you would like your customer to have (each subsequent one will replace the previous temporary code). When the temporary licence expires, the licence will always revert back to the permanent licence that they had previously (unless the permanent licence expires in the interim). Issuing another Permanent licence will replace the existing Permanent licence (as will issuing another Temporary licence will replace an existing temporary licence). The licence type is set on the Registration window - and must match in both the Registration program and on the RegisterProduct window in your application.

The temporary licence (by nature) - will contain more features than your permanent licence. The reason for a temporary licence is to try out temporary features. Once the temporary licence expires, the licence will fall back to the permanent one - IOW the temporary licence is at a higher level to the permanent one. Temporary Licences are Level 2 licences, while Permanent Licences are Level 1 licences.

Because temporary licences should be temporary, the expiry period should be a short period (say 30 days) in order to avoid the following issue:

Warning Note: The temporary licence will always supersede the Permanent licence. This means that if you assign your client a new Permanent licence, while the temporary licence has not yet expired, it will not be used until the temporary licence expires. If you don't want this feature, then hide the Type drop down in the registration application, and always assign the licences to permanent. If you want to assign more features in a permanent licence (than in a currently unexpired temporary licence) - then you need to issue both the temporary and the permanent licences (so that the current temporary licence will be replaced by the new temporary licence with the new features).

Note: Don't confuse a temporary licence with a demo licence. A demo licence is a permanent licence type - a temporary licence is only issued to an existing permanent licensee to try out new features (so the licensee is still registered).

Use the ds_CurrentLicenceDetails function to return the Licence type (as well as other licence details).

The mechanics of Licensing

1. Your program creates a .Lic file in a common directory (normally the data directory) which it locks while it is open.
2. The next instance of your application that runs, will find the existing .lic file in the data directory and will attempt to open it. If the first instance is still running (and will still have the file locked) then this new instance of the application will fail to open the .Lic file. It will then check how many licences are available for use and create another .lic file (if the number of licences has not yet been exceeded).
3. Each instance of you application will continue with step 2 above until the number of licences has been reached, at which point the next instance of the application that is run, will fail.

In order for Licencing to work correctly, each instance of your program must be set to create and/or use the Licence file in the same place as all the other instances. This is set on the Files tab of the Secwin Global Extension template of your application. If your application is opening more times simultaneously than you have issued licenses for, then it almost certainly means that each instance running is using a different path for the license files. For more details on locating the Security file, peruse the Locating The Security File section of this document.

For handcoders that care - take a look at the Secwin Data Types section of this doc for more details on the data structures required for licensing and registration (in particular the ProductDetailsGroupType and the LimitsQueueType data structures).


The Security File

Creating the Security File

Secwin makes use of a data file to store user names and access rights etc. This file is called dssw4.TPS and is stored (by default) in the Windows directory. (You can override the location - see Locating the Security File.) Also, by default, your program won't create the security files. If it did then users could bypass the security by deleting dssw4. (You can also make your program create the files by using the ds_CreSec function.)

Tip : If you used the QuickStart settings to get going then you program is creating it's own security files. This is not a problem if you are using Licensing, but if you aren't using licensing the strongly consider changing to one of the options below.

Tip : Secwin ships with an example called Cresec which creates the security file (\clarion\3rdparty\examples\secwin\cresec.) For your convenience this is also shipped as a pre-compiled Exe into your \clarion\3rdparty\bin directory.

You have 4 options for creating the security file.

Locating the Security File

For Flat file systems (like TPS): By default the Security file will be placed in the Windows directory.  This makes it harder for people to simply copy your program from one machine to another.  However in network situations this approach doesn't work because typically the users need to share the same security file. If the the file is shared they can use the program, with their login, from any machine. Security administration is also much easier if the file is shared.

There are ways to set the location of the security files.

For SQL files: The security files are located in the database and/or schema specified in the connection string. See the Security-File Driver section of this document for more details on connecting to the server. Secwin will create a handful of data files prefixed with Secwin_ which it will use to store the necessary security data in.

Security-File Driver

Secwin supports storing the security file using a variety of different drivers. These include support for Oracle, Microsoft SQL, PervasiveSQL, IPDriver and ODBC drivers, which means you can use a variety of different databases such as Interbase or MySql. You can select from the list of supported drivers on the Global Extension, on the Files tab. Some drivers may have different options. These are discussed in detail below. If you would like a new driver added to the list then contact Support@CapeSoft.com .  

All the following drivers are included in the Secwin install (unlike Secwin 3 which required an additional install for each driver required).

If you are using a file driver other than the Topspeed or Btrieve drivers then you will need to enter the owner string in the Owner field. This is the Owner attribute as it would normally appear in your dictionary. The owner format for the different drivers is as follows:

Oracle

User/pwd@sn where User is the username, pwd is the password, and sn is the Service Name or SID of your Oracle Database.

Microsoft SQL

Host,db,user,pwd where Host is the IP or Host name of the Database server, db is the Microsoft SQL database name, user is the username, and pwd is the password.

PervasiveSQL

Host|db,user where Host is the IP or Host name of the Database server, db is the database name, and user is the username. Please note the pipe "|" character used between Host and db.

ODBC

Dsn,user,pwd where Dsn is the Data Source Name, user is the username, and pwd is the password.

Tip : The ODBC driver comes with special support for MySql and Ingress. On the Global Extension Files tab, first select ODBC file driver, and then MySql (or Ingress) Database type. For all other ODBC connections, use the Other option.

Via ODBC, Secwin explicitly supports: MySQL, Ingress, Interbase and PostgreSQL. You may have success with other databases, if so - please let us know so that we can add these to the confirmed list.

IPDriver

Peruse the IPDriver Compatibility section of this document to include IPDriver support for Secwin.

Tip : See the various examples for these drivers in your clarion\3rdparty\examples\secwin directory. Read more about these Secwin Examples.


If you are using the Topspeed or Btrieve driver, then you can leave the Owner field blank, and the default one will be used.  However you can enter your own Owner field here if you want to.

Tip : If you set an owner here for Topspeed or Btrieve then the security file you create will not be compatible with other applications that use a different owner. Therefore if you set the Owner field yourself then you must set the position of the file to be in the Application, or Data directories. (See Locating the Security File.)


Of course if you set the owner, then you're able to import the security files into your dictionary, and manipulate the files directly in the code. We obviously can't stop you doing this, but we advise against it. By altering the files directly you run the risk of bypassing the validity checking that Secwin would normally do. For example Secwin doesn't allow you to delete Super Users, although in your own code this would be a trivial thing to do.

Note: If you are using Multi-Proj's Driver Substitution, then peruse the Using Secwin in a Multi-Proj application section of this doc for details.


Customizing the Look and Feel of Secwin Windows

Changing the Logo on the Secwin Windows

On all of the Built-In Secwin windows is a little padlock logo. This logo can be replaced by your own logo, or removed completely, using the ds_SetLogo function.

Making your own Secwin Windows

As from version 3.1 all of the Secwin windows can be replaced with your own Windows. This allows you more creative control over how the windows look, and it's also an important part of making the program compatible with Web Builder and ClarioNet. 

Creating your own Product Registration window

Open your application in the Clarion IDE and use the "Create RegisterProduct window" (ABC or Legacy) to import a default SecwinRegisterProduct window (in Multi-DLL apps, it's probably best to do this in the DataDLL):

  1. Select the Template Utility item from the Application menu.
  2. In the Select Utility list, scroll down to the Class Secwin and find the CreateMyRegisterProductWindowABC/Legacy and select it. You will see a SecwinRegisterProduct procedure is now added to your application.
  3. You need to call the SecwinRegisterProduct window from the control that you previously added the Call RegisterProduct code template - or where from where you called your MyRegisterProduct window.

Open the window formatter for the SecwinRegisterProduct procedure, you can now hide controls that are not required (if you are not using all the Licence features). If you don't use an entire tab, you can modify the accepted code in the Back and Next buttons to skip that particular tab. Don't delete controls in case you require those features at a later stage. Have a look at the Including additional Fields in the Licence if you require the use of additional fields in your licence.

Right-click on one of the controls, and you be able to set the following:

On the Messages tab you will be able to set the text of Registration success and failure:

On the Counters/Limits tab you can enter any limits/counters that are used in the activation code.

These must match those in the application issuing activation codes (although these are case insensitive). If you are using table limits, then these will be automatically added to the list from the Global Extension template, and will only be displayed here. You will need to add the procedure counters manually though. Peruse the Using Counters section of this doc for more details.

Note: If you're wanting to use Secwin Online Server to manage your Product Registrations online, then you can add the Secwin Online Server controls now.

Creating your own Global SetAccess window

Included in Secwin is the ability to create a Global SetAccess window. You can create one window to SetAccess rights throughout the entire application for each user. Here are the steps in order to do this:

  1. In the Secwin Global Extension template, on the Options tab you will find a set of prompts to generate an include file (the default extension is .SAC) for all the security points in the application. This file is only used at compile time and does not need to be deployed with your application. Check the Generate inc file with Access points everytime checkbox, and enter a unique include filename that will contain the additions to the Access Points Queue (more about this queue later). For Multi-DLL apps, you'll probably want to leave this unchecked in the root dll (where your Secwin procedures are) and only check this in your other Secwin applications that use UserScreenSecurity.
  2. Run the Create AccessControl windows template utility
  3. In the extension templates of the SecwinSetAllAccess procedure, you will find a Secwin's set access globally control template. In there is a list of the include files that need to be used to create the AccessPoints Queue which is used in the procedure to display all the access points of the application(s). The one that is in the SecwinGlobalExtension template should be automatically added.

    Note for Multi-DLL users: You'll need to add any others that are created (if this is a Multi-EXE or Multi-DLL application) by other applications related to this one. You'll probably want to delete the root dll's sac file from the list, as it is superfluous (i.e. it doesn't contain any access points).
     
  4. If you have not already added the Create Secwin Menu extension template, then do that now.

The SetAccess window that is added to your application has two list boxes: one for users and one for the AccessPoints.

Selecting a User in the Users list, will show the AccessPoints that this user has access to in the AccessPoints list (the ones that are checked, he has access to and the ones that aren't he does not have access to). You can edit a user's access rights by Double-Clicking the relevant AccessPoint's checkbox in the Access Points list.

To view the users that have access to a specific Access Point, use the Access Points tab:

Selecting an Access Point from the AccessPoints list will show which users have access to that point highlighted. You can edit a user's access rights by Double-Clicking the relevant User's checkbox in the Users list.

You can add users and user groups using the respective buttons on the window.

Note: Only supervisors have access to this window.

Creating your own User Browse & Form windows

The easiest way to do this is to use the Create AccessControl windows Template Utility to make a set of AccessControl windows (including the User Browse and forms).

Creating your own Login window

The easiest way to do this is to use the