Version www.capesoft.com Updated Monday 30 November 2009

JumpStart	Examples	FAQs	Version History

What's new in Secwin 4?

Documentation
	JumpStart	User Guide
	Template Reference	Technical Reference
	Other Information

Contents: User Guide
	Introduction to User Guide: Adding Logins and Passwords Adding Screen, and Control, Access Control What to read next Access Control: Overview of Access Control Features Login and Password Access Control Operator Browse and Form Screens Screen Security Access Control Set Access Rights Screen Ancillary User Functions User Groups Work Groups Bypassing Access Control Licensing and Registration : Overview of Licensing Features Some Activation Code secrets Branding Hardware Copy Protection Using Levels Automatic Demo Licenses Using Optional Modules Using Network Copies Using Expiry Dates Using Counters Including additional Fields in the Licence Using an XML file to transfer the licence details Using Different Licence Types When the License Fails   The Security File: Creating the Security File Locating the Security File Security-File Driver Handling Corruptions Customizing Look and Feel of the Secwin Windows: Changing the Logo on the Secwin Windows Making your own Secwin Windows Creating your own Product Registration window Creating your own Global SetAccess window Creating your own Change Password window Creating your own Change Login window Using SecWin in a NetTalk WebServer (coming soon) Support: FAQs Secwin Error Messages Technical Error Support Miscellaneous: Using Secwin in MultiDLL applications Converting from Secwin 2.x to Secwin 3.x Secwin Examples Super Users Translating Secwin Windows PIN numbers Utilities shipped with Secwin ClarioNet / WebBuilder compatability Using Secwin in a Multi-Proj application Advanced Programmer Functions: Secwin Template Reference Secwin Low Level DLL Functions Release History

Things you absolutely have to know before you start

• The first half is known as Access Control and governs who uses the program. An example of this is the Adding Logins and Passwords, and the features go on from there. These features allow your client to restrict access to his application. A good place to start installing these features is using the JumpStart section entitled Adding Logins and Passwords. Screen and Control Access Control is the next part of the equation, and the advanced features can be found in Access Control.
  
• The second half contain features collectively known as Licensing and Registration. This covers what you might think of as Copy Protection. These are features that make sure that you get paid for your software. Start with Adding the Licensing and Registration features, and then move on to Licensing and Registration.

Features included in Secwin4

Access Control:

• Multiple user groups per user
• Permitted Control Groups per screen increased from 30 to 252
• Get User Password (see Using an encryption key for details)
• Global Access setup in one place
• Outlookbar Support

Licencing and Registration Control:

• Multiple LicenceTypes: Permanent/Temporary (see Using Different Licence Types).
• Multiple Counters + easy implementation of Table restrictions (see Using Counters).
• Registration via XML file (see Using an XML file to transfer the licence details)
• Upgraded licence code encryption.
• Variable Activation Code Expiry Period.
• Additional user-defined fields to include in the licence.

Additional Features:

• WebServer support (using Secwin to manage your Webserver apps access control rights) (coming soon)
• Replicate support (Secwin files replicated across sites) (coming soon)
• All internal strings increased to 128 chars (SerialNumber, login, password, etc) - and some 252 chars.

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.
   

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:

• PRODUCT details ( the License name and Seed code used in step 1b )
• The CUSTOMER details ( Company Name )
• REGISTRATION details ( Serial Number, Expiry Date, number of copies, Counters/Limits, Level, Optional Modules, etc) which you set.
  
  You can either generate an activation code immediately, issue an xml file containing the registration details or print out a simple report containing all the details and a code.
  

JumpStart: Adding Logins and Passwords

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

c) On the Options tab, set the Function Overrides as follows (for Multi-DLL users, this will be in your data dll only):

Note: SetAccess must be set to SecwinSetAccess NOT SecwinSetAllAccess.

Note: For Multi-DLL users, you'll want to compile the security dll (normally 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.

For Multi-DLL users, in other applications (not the security dll) check the Functions are in another application checkbox and type in the external procedure names of the procedures that you will require in this application (typically the SetAccess window only for most apps, except the one that you log in with - then you'll need all the procedure names).

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:

• Change Login Item Procedure: SecwinChangeLogin
• Browse User Groups item: SecwinBrowseUserGroups
• Set User Access item: SecwinSetAllAccess

5. For Multi-DLL applications, you need to follow the Using Secwin In MultiDLL Apps guide in this document.

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 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.

JumpStart: Adding Screen, and Control, Access Control

Unique Bit Position

Name

Use Equate

List box Column

Action

Attach Other Controls

What to Read Next

Access Control

Overview of Access Control Features

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

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

First name & Last name

Login

Level

Default Access

User Group

Workgroup

Screen Security Access Control

Set Access Rights Screen

Ancillary User Functions

Change Password

Change Login :

Lock Screen :

User Groups

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

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

Work Groups

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

Product Branding

Levels

Automatic Demo Licenses

Optional Modules

Concurrent Network Copies

Users currently logged in

Expiry Dates

Counters

Some Activation Code secrets

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

Branding using Logo Screens

Hardware Copy Protection

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

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).

Using Optional Modules

Using Network Copies

Using Expiry Dates

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

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

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.

Some tips on creating a registration (using the registerabc application). Run the registerabc application - and to create a registration:

• Create a product entry - making sure that your product name and seedcode (you enter) matches the licence name in the Secwin Global Extension of your application.
  
                         
  
• If you have implemented table limits (or a procedural or handcoded counter) you need to add the limit to the product entry. When creating a registration, the registration will contain a record for each limit that you added to the product (in the products table). You can override the default limit (or count) that is automatically primed in the new registration on the limits/counters tab. The counter description used in the registerabc application must match the 'Counter to decrement' field in the UserScreenSecurity template prompt in your application. If you have stipulated table limits in the global extension, then you need to use the exact table name in the description in the registerabc application.
  
  

  Showing Table Restrictions
  Showing a procedural counter
  R# = ds_CheckCounter ('Default Counter',1) Showing a hand-coded counter

       

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

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

• Ship a dssw4.tps file with your application.  If they delete the dssw4 file then the program will have to be re-installed. This is the simplest solution. (NB: Don't replace if there already)
• Ship a separate program, like Cresec.Exe to create the security file. This program would need to be controlled by a system administrator.
• You can add this functionality to your program by setting the switch on the Secwin Global Extension. Note this option is only recommended for very low risk sites, or for programs where licensing is turned On. If the security file is deleted, and licensing is turned on, then the program would have to be re-activated anyway.
• You can add this functionality to your program by using the ds_CreSec function in conjunction with some user input. This is for advanced programmers only.
PIN numbers are used to add even greater security. They have to be placed in the dssw4 file by the developer, and is known only to him. In other words although CRESEC is freely available to anyone who knows where to look, by using PIN numbers a developer can ensure that only a dssw4 file stamped by him are valid. Pin Numbers are not not necessary if you are using the Licensing features of Secwin. See Pin Numbers for all the details.

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.

• Use the settings on the Global Extension to set the file to be in the EXE directory or the Data Directory. This is the easiest method and is recommended. If you use the Data Directory option, and you use a variable for the path, then you need to prime the variable in the Program Setup Global embed point in your program.
• Use settings in the Secwin.Ini file. (see below)
• Use Settings in the Win.Ini (If the Secwin.Ini doesn't exist). (see below)
• Use the ds_SetPath command in your code. For advanced programmers only.

Secwin.Ini

To set the location via the Secwin.Ini file, you must have a file called Secwin.Ini in the Current Directory where the application starts. Inside the file is a section entitled [Secwin] and a setting Path=xxx where xxx is the path. If xxx is set to HERE then the current directory will be used. If it's set to EXEDIR then the Application Exe directory will be used.


Win.Ini

To set the location via the Win.Ini file, you must have a file called Win.Ini in the Windows Directory. Inside the file is a section entitled [Secwin] and a setting Path=xxx where xxx is the path. If xxx is set to HERE then the current directory (not the windows directory, but the 'Start-In' directory) will be used. If it's set to EXEDIR then the Application Exe directory will be used.

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. Alternatively, use www.connectionstrings.com to assemble a connection string that can be used to connect to the database.

If you would like to use a different schema other than the default, you can set this in the template entry prompt on the Files tab of the Secwin Global Extension template.

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.

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.

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
• Creating your own Global SetAccess window
• Creating your own User Browse & Form windows
• Creating your own Login window
• Creating your own Change Password window
• Creating your own Change Login window
• Creating your own SetAccess window
  

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:

• Automatically register when an XML file is dropped. Checking this will load the XML and attempt to register when the XML file is dropped onto the XML region in the Register Window. Otherwise, the settings will simply be loaded and the user will need to manually click the register button.

• Activation code can only be used once. The activation code is stored in history, and may not be used on the same PC a second time.

• Dealer field in the licence. Detext in XML: if the dealer field is included in the XML file, then the activation code checker will assume that the Dealer field was included when generating the activation code. Force use: will include the dealer code in the activation code. No Dealer: will not include the dealer in the activation code checker (whether the code is in the XML or not).

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 other SAC files (to this list) that are created 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 normally superfluous (i.e. it probably 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 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 way to do this is to use the Create AccessControl windows Template Utility to make a set of AccessControl windows (including the Login Window)

Creating your own Change Password window

The way to do this is to use the Create AccessControl windows Template Utility to make a set of AccessControl windows (including the ChangePassword window)

Creating your own Change Login window

The easiest way to do this is to use the Create AccessControl windows Template Utility to make a set of AccessControl windows (including the ChangeLogin window)

Creating your own SetAccess window

Use the Create AccessControl windows Template Utility to make a set of AccessControl windows (including the SecwinSetAccess window). You are now free to examine the SecwinSetAccess procedure, and to tweak the visual look & behaviour as you like.

Using SecWin in a NetTalk WebServer

• You'll need to create an application that can create a supervisor for the webserver.
• Import the SecwinOperators.txd into your dct.

Miscellaneous

Using Secwin in MultiDLL applications

For and example of a MultiDLL application using Secwin, and the ABC templates, see the \clarion\3rdparty\examples\secwin\MultiABC directory.

There are 2 kinds of Application in a Multi-DLL project. The first kind is the Root, or Data application. This typically contains all your file structures.  The second kind is any of the other APP files, other DLLs and EXEs that make use of this Data DLL.

Note: Follow the Jumpstart for adding support to your multi-dll application. In addition to that, you need to do the following:

If this is the Root Application then 
1. go to the Global Extension, to the Multi-DLL tab. 
2. Click on This is part of a Multi-DLL Application. 
3. Click on Export Secwin data.

If this is Not the Root Application then
1. go to the Global Extension, to the Multi-DLL tab. 
2. Click on This is part of a Multi-DLL Application. 
3. Click off Export Secwin data.

In the global extension on each application:

1. You need to set the "Unique application name" (in the Secwin global extension template) the same in all the applications.
2. The "Licencing" tab should be setup the same in the all your app files (i.e. the data dll, the main exe and any additional dlls that you want to add Secwin to).

For some assistance with additional settings, check out the Global Extension template

Converting from Secwin 2.x to Secwin 3.x

One of the goals when creating Secwin 3.0 was to keep it as compatible as possible with Secwin 2.x.  There are very few issues to worry about when converting, but known issues are described here.

Distribution

The Secwin DLL names HAVE CHANGED! See the Distribution section, in the Other Information section for specifics.

Multi-DLL Applications

Multi-DLL support has been simplified a lot, but this means that there will be a few things for you to remove from your existing apps.

1. In your Root DLL remove the QAdd, QGet and QDelete functions.
2. In your Root DLL go to the Global Data button and remove AppNameDesc and AppNum.

Btrieve Users

Support is being added for a number of different file drivers. The old Use Btrieve switch has fallen away, and been replaced by a drop-down. This can be found on the Global Extension, on the File Tab.

Secwin Examples

Secwin ships with quite a few examples, so sometimes it's difficult to find the example you're looking for. Here is a list of all the examples, and what they're trying to show you.  Al the examples are found in the \Clarion\3rdparty\Examples\Secwin directory.

Super Users

Note : They are probably not what you think. Read the next bit carefully to understand them.

The need for Super Users arises where you, as the developer, need to maintain a permanent ability to access the program at your client's site. While this may seem like a defacto requirement of all programs, it is often not ideal. While it may be common for developers to have 'back doors' into their own programs, these back doors provide a substantial security risk (Anyone seen the movie War Games recently ?)

Of course on some sites you do need to make sure that your login rights are preserved, because your users are likely to do things like lock themselves out, or forget their own passwords. Secwin offers a SuperUser feature for coping with these situations.

Firstly - what a Super User is NOT. It is not a Back Door which will always let you in.

Essentially a Super User is simply a user who cannot be Deleted. The user still needs to be added in the Normal Way. The Super User code is normally set to be a Supervisor, although he can also be set to be an Operator, or even set to No Access. The Super User can be seen by the customer, but cannot be deleted by the customer.

The User Login template has been modified to support this feature. There is a special tab containing the Login Code for the Super User. Remember the User must be created in the normal way, setting the code here will not automatically add the user.

As with most features, this feature is optional and should not be used on sites requiring a high level of security.

Translating Secwin Windows

Secwin allows you to translate any of the windows into any language.

First one or two bits of terminology.
A language file (note the small letters) is a text file containing a list of translations, from the original English into whatever language you like. The exact format of the file will be discussed later.

LanguageFile (note the big letters, and the lack of a space) is a SecWin.INI file parameter, containing a DOS file name (including drive and path) of a valid language file. This file normally uses the .IRF extension.

LanguagePath is a SecWin.Ini parameter that is used with the ds_SetLanguage function to change languages on the fly. It contains a valid drive and path.

Choosing a language

Secwin allows you to choose your language using two methods, the first is via the use of an INI file, and the second is via a function (ds_SetLanguage) at runtime.

When your Secwin enable App is started Secwin looks for two parameters namely LanguageFile and LanguagePath. Secwin looks first in the Application directory, in the Secwin.Ini file, in the [Secwin] section. If either, or both are not there then it looks in the Windows directory, in the Win.Ini file, in the [Secwin] section. If LanguageFile is still not present then it defaults to a file called Secwin.Irf, in the Windows directory. If LanguagePath hasn't been found then it defaults to the Windows directory. If LanguagePath is set to 'Here' (no quotes) then it will be set to the application directory.

LanguageFile is a full path- and filename to a valid Secwin language file. The exact format of a valid Secwin language file is discussed a little later on. Secwin uses LanguageFile as the default language file containing the required language phrases. If this file does not exist, then Secwin uses the normal English phrases on the screen.

During the running of your application you can set, or change, the language file being used by calling the ds_SetLanguage function. This function takes one parameter, the name of a language file. This parameter is added to the LanguagePath parameter (discussed above), and then used as the current language file.

Example

Inside the Secwin.Ini file...
[Secwin]
LanguageFile=c:\Windows\Spanish.Irf
LanguagePath=c:\Lang

Using the above Secwin will default to using the Spanish.Irf language file in the Windows directory, on the C Drive.
At runtime the application could call the ds_SetLanguage function, like this...
ds_SetLanguage('Russian.Irf')

Which would change Secwin to use the Russian.Irf file, in the Lang subdirectory on the C Drive.

The last point to discuss is the structure of the Language file itself.

Format of a Secwin language file

The format of a Secwin language file is very simple. It is made even simpler by the fact that a sample language file (English.Irf) ships with Secwin, and thus simply copying this sample file and translating the English terms is all you really need to do. Note that Secwin (by default) doesn't use the English.Irf file, it is only included as an example.

Inside the file there are a number of Sections, each one enclosed in a set of square brackets, like this... [spLevel Text]
Inside each section are a number of field equates that identify each visible text field on the screen. On the right of the equals sign is the actual text that would be displayed. For example the following.

[spLevel Text]
Level:Unknown=Desconocido
AccessLevel:2=Operador
AccessLevel:0=Sin acceso
AccessLevel:3=Supervisor
AccessLevel:-3=Todos Acceso
AccessLevel:-10=Acceso

By replacing the text to the right of the equals sign, you can get the translated text to be displayed as anything you like.

At the top of the file is a section called [Intl], and this has a single entry called sLanguage. eg

[Intl]
sLanguage=sp

This is used to find the correct section later on. You'll have noticed above that the function name (e.g. ds_OperatorBrowse) is prefixed with this. This is a requirement of the way the support works. If you change the value in the Intl section, then you must change the prefix in all the other sections as well.

At the bottom of the file is a section called [enuMessages]. This section contains the messages that appear when SecWin needs to communicate with the user. You will need to translate these messages as well.

Note: Because by default the Secwin windows are included in your application, only the MessageText and level text will require translation. The old DLL windows will still be supported for Secwin3 applications using the Secwin 4 DLL.

Using a different date picture:

To set the different date picture, then you need to enter the following in to the language file:

[engMessages]
datepic=@d6

Using alternative licence level notifications:

You can use alternatives to the default licence level indicators in Secwin (i.e. Demo, Lite, Standard, Professional and Enterprise). Setup translation in the normal manner (as indicated above) , and "translate" the licence level text to display what you would rather display.

[engLevelText]
Level:0=None
Level:1=Demo
Level:2=Lite
Level:3=Standard
Level:4=Professional
Level:5=Enterprise

PIN numbers

One of the only current methods of compromising SecWin Access Control (where licencing and registration aren't used) is through the replacement of the dssw4 security file by an empty dssw4 file. PIN numbers prevent this from being effective by requiring that a dssw4 file be "stamped" with a PIN number before the Application will accept the dssw4 file as valid.

The PIN number system introduces two new functions, and their associated templates. ds_SetPin is used to stamp a PIN number into a DSSW file.

If you choose to make use of the PIN number system, then you will need some way of stamping the dssw4 file with the pin number. This can be done in a number of ways, some of which are laid out below!

1. Use another EXE program, over which 100% physical control can be maintained. It should not be accessible to un-authorised users, and should be treated as a physical key. The PIN number itself is hard-coded into the program, and can be run by anyone with access to it. An example of such a program ships with SecWin and is called HARDPIN. This can be found in the \Clarion\3rdparty\Examples\Secwin\UsingPin directory. The advantage of this method is that a person doesn't need to remember the pin number - they simply need to run the program.

2. Use the enclosed SETPIN program which ships with SecWin. (This program can be found in the \Clarion\3rdparty\Examples\Secwin\UsingPin directory.) This program requires that the PIN number be entered by the user. The user will then need to know the correct PIN number in order to properly stamp the dssw4 file.

Using an encryption key

You can use your own encryption key to essentially encode the secwin_operators table so that it is unique to your application. This means that no other application (that doesn't use the same unique encryption key that your application uses) can access the secwin_operator's table that your application uses. This means that, because your secwin_operator's table is closed to the outside world and completely in your control, you are able to use the ds_ResetUserPassword and ds_GetUserPassword functions in Secwin - to enable a supervisor to reset a user's password (or get it and send them the password using a transport mechanism of your choice).

For handcoders, you'll need to call the ds_SetEncryptionKey function before initializing secwin (or template users - there's a setting in the template that you can set to do this). You cannot use the ds_ResetUserPassword and ds_GetUserPassword functions without using a unique EncryptionKey.

Note: Once the ds_SetEncryptionKey function has been used by your application, and your application has been run on the Secwin data tables, then only your application will be able to read the secwin operators table. There's no going back to default encryption again.

You can take a look at the example application in the Demo_AccessControl folder that uses these functions.

Utilities Shipped With Secwin

The FileFixer Utility

This utility is provided in order to generate an Security code that will enable Secwin to internally repair corrupted AccessControl tables. If your user's tables have been altered by an application other than Secwin, then the encrypted CRC will not match the CRC of the fields in the table. Your user will be confronted with the following message:

If you have entered an email address in the Secwin Global Extension template (on the Options tab), then your user will be able to easily generate an email requesting an activation code in order to easily acquire a Security Code to copy and past into the entry field provided. The must simply click the "Create Request Email" hyperlink. If you have not entered a valid email address, they will need to enter the Unique Identifier into an email (or over the phone) - which you can use to create a Security code.

The file fixer utility is located in the Clarion\3rdparty\bin directory (called SecwinFileFixer.exe) - and is used to generate the necessary Security code to repair the AccessControl tables.

In order to generate a valid Security code that the user can enter to get the program going again, you need to do the following:

1. Enter your product (in the Browse Products procedure) - include a description (in the Product Name field) - and the application name (this is the Secwin Application name entered in the Secwin global extension template).
2. Enter the Customer details (in the Browse Customer procedure) - include the customer name, Email address (this will be the from email address of the Request Email) - and the UniqueIdentifier included in the email.
3. Next is to create a Request in the Browse Requests procedure (this is an incident file). Here you can stipulate how long the Security code issued is valid for, and how many times the Security Files can be repaired during the course of the Security file's validity. Once you've entered all the details, click the send email button - and use your email client to send the email to the client.

ClarioNet / WebBuilder compatability

Secwin now supports full compatability with both the standard Web Builder templates included with Clarion, as well as the ClarionNet add on. For the sake of simplicity in this section I'll refer to WB compatability. This includes both the Web Builder and ClarioNet products.

The only thing you need to do to make your program WB compatible is to create your own versions of the Secwin screens. (You may have already done this anyway for design reasons.) For information on creating your own Secwin windows see the section called Making your own Secwin Windows.

Using Secwin in a Multi-Proj application

Secwin is completely compatible with a Multi-Proj application - however you may need to tweak some settings in order to get the two templates to operate correctly. Typically you'll need to do this if you are using the Driver Substitution feature in Multi-Proj. If you are creating an IPDriver project (for example), then you'll need to make the following changes:

1. In your Secwin Global Extension template, find the Files tab and check the Manually include the correct Secwin driver checkbox located in the Multi-Proj support prompts groups.
2. In your Multi-Proj template, on the Versions tab, locate the project for the IPDriver substitution, and double-click it.
   
   
   
   On the Resources tab for this Multi-Project version, enter the Secwin IPDriver lib - s6ipdx.lib (if it's a stand-alone project, and not a localmode project)
   
   
   
3. In your application, you'll need to override the driver owner setting generated by the Secwin template in your default module (your main exe):
   
   ds_InitFileCallback()
   ds_SetAppName('SecwinDemo')
   COMPILE('****',TOPSPEEDDRIVER)
   ds_SetPath('HERE',,)  ! secwin
   ****
   COMPILE('****',IPDRIVER)
     SWDRV::OWNER = 'IP_S4TPS6' & sub(IPDRV::OWNER,instring('.',IPDRV::OWNER,1,1),255)
     ds_SetOwner(SWDRV::OWNER,SWDRV::OWNER)
   ****

For a list of the matching drivers to their Secwin projects, see the Distribution section of this document.

IP Driver Compatibility

Installing

1. Copy the IP_S4TPS6.DLL from your \clarion\3rdparty\bin directory to your \ClarionDataServer directory. If you haven't already done so also copy the Clarion Runtime DLL's to the \ClarionDataServer directory - including C60RunX.DLL, C60DosX.DLL and C60TpsX.DLL.
2. Run the RmAdmin program, and register the IP_S4TPS6.DLL. (This is as you would do for your application's IP driver DLL - which is laid out in the documentation provided by SoftVelocity that comes with the IPDriver install)
   

[ TIP : when deploying your application, i.e. deploying the ClarionDataServer, then you will need to do steps (1) and (2) as part of your deployment ]

Changes required to your application

The SV IPDriver Client Global Extension is active in your app then Secwin will use the IP Driver connection (so you must have the SV IPDriver Client Global Extension added to your application). 

1. Check that the the File driver (set in the Activate Capesoft's SecWin template) - Files tab, is set to Topspeed.
2. Go to the Files tab of the Secwin Global Extension template, and in the Security File - Position group, select the 'Data Directory' option and enter 'HERE' (including the quotes).

Note: If you are adding Secwin to an IPDriver application (Multi-DLL or single EXE), then you can follow the steps in the JumpStart as per a normal application, with the above amendments to the JumpStart instructions.

Using a sub-directory within the ClarionDataServer

The IPDriver supports multiple database driver DLLs, which means that you can have a number of Secwin IPDriver DLLs running on the same server, each with it's own set of security files that it is maintaining. This is what you need to do in order to use a subdirectory within the ClarionDataServer:

1. Create the subdirectory within the ClarionDataServer directory (let's call it MyDatabase)
2. Copy the IP_S4TPS6.DLL to this directory (i.e. c:\ClarionDataServer\MyDatabase)
3. In your application, go to the Files tab of the Secwin Global Extension template, and in the Security File - Position group, select the 'Data Directory' option and enter 'MyDatabase\' (including the quotes). You could use a variable here as well (without quotes) if you wanted to load the directory at runtime. The important thing to remember is that the path entered is with respect to the ClarionDataServer directory (normally c:\ClarionDataServer\)
4. If you are not allowing your program to create security files, then you need to copy the dssw4.tps file to the c:\ClarionDataServer\MyDatabase directory.

You can alternatively have the secwin data files residing in a different sub-directory to where the ip_s4tps6.dll resides.  By adding the following to the Program Setup embed - immediately before the Secwin - After SetOwner and SetPath embed point. Note that the template setting in the position group still indicates where the ip_s4tps6.dll resides.

ds_SetPath(GLO:IPServerSubSir)           !GLO:IPServerSubSir must contain the sub dir containing the dssw4 file.

Limitations

1) Only support for the TPS driver (i.e. dssw4.TPS) is currently available. Support for other drivers will be made available on a demand basis.

Note: An example ships with Secwin (see Secwin Examples in this doc for details). If you are having difficulties getting your IPDriver enabled application to work, try this example t test where the problem lies.

Advanced Programmer Functions

This section describes some of the advanced functions available to you the programmer, and where you might use them. 

ds_BuildKeys

This function can be used to rebuild the keys stored inside the security file. The primary reason for using this function is when you want to change the Locale settings for your program. In Clarion if the Locale settings change then keys need to be rebuilt.

ds_Crypt

This is a simple function for doing simply text encryption. Pass the string to the function  to encrypt it, and pass the encrypted string to the function to decrypt it. 

ds_InsertUserEx, ds_ChangeUser, ds_DeleteUser

These functions allow you to add to and edit the list of users. 

ds_UsersEx and ds_UsersUserGroups

This function returns a Queue containing all the users currently in the file. The Queue contains their First name, Surname, Login Code, and User Group setting.

ds_SetPath

The most common way to set the location of the Security file (dssw4) is to use the Secwin.Ini file. However you can also set the path in code using this function.
 

 

Global Extension : Activate Secwin features

Purpose

This is a Global Extension template which needs to be added to the Global area in order for the Secwin features to work.

To Include in your App

1. Open your App in the usual fashion
2. Choose Global Properties from the Edit menu ( You can also click on the Global button to get here )
3. Click on Extensions
4. Click on Insert
5. Choose Activate Secwin Features

Options

• Disable All Secwin Features - If this option is on then all Secwin features in this application will be disabled. This is very useful if you suspect Secwin is causing a problem. By switching it off, you can confirm if Secwin is the source of your problem.
• Unique Application Name  - a unique name for this application.

• Disable Licensing support - If you only want to use the Access Control portion of Secwin, then you can use this checkbox to disable Licensing throughout your entire application.
• License Name - This is the name of the license for this application. When generating activation codes this corresponds to the Application Name (or the name of the product).
• License Seed Code - This is the number that makes the activation codes for your application different to other Secwin users. Chose any random number here. Use this number when generating Activation Codes.
• Disable concurrent copy checks - Secwin will issue a licence file for each concurrent copy of the program that is allowed to run (as issued in the licence). If you check this, then you will effectively disable concurrent copy checking (i.e. allow infinite amount of copies of the program to run on that licence).
• Disable all "valid date" checks - Prevents the app from comparing the date of the dssw4 file to the computer's date to check if the date is being reset to a previous date. This is useful if you have multiple different applications using the same dssw4 file.
• Disable Licence File registry check - If you check this, then you disable extra registry checks that secwin does to match the dssw4 file with a value in the registry (per product). You would need this checked if you have more than one dssw4 file, or you have multiple applications accessing the same dssw4 file.
• Tables with Record Limits - enter the tables that you would like to provide a limit on (depending on the licence issued by the registration application). See Using Counters for more details.
• Limit Warning message - this is the text of the message that appears when the above table limit is attempted to be exceeded.

• This is Part of a Multi-DLL Application - If this APP is part of a Multi-DLL application then click this on.
• Export Secwin data defined in this DLL - If this is the Data DLL then tick this option on.

• Select Driver - Allows you to select the file driver that will be used to store the security files. By default the Topspeed driver is used. See Security-File Driver for more information.
• Database Type - Only shown when ODBC driver is selected, this takes care of those niggly differences between sql databases.
• File Owner - If you use the Topspeed or Btrieve drivers then this option is not used. With the other drivers this option is required. Each driver will display the format for it's owner string. Eg: The MSSQL owner label is host,db,user,pwd i.e. IP or Hostname of MS SQL Server, databasename, username, password. See more info at Security-File driver. Use this to set the Owner property for your security files.
• Allow program to create security files - Allows your program to automatically create the dssw4 security file. Only recommended for sites using licensing, or which have a low level of security. See also Creating the Security File.
• Security Files CRC Check - Enabled (by default) - means that the Security files are constantly checked for an illegal write (not made by the Secwin DLL).
  Disabled (only recommended for sites using licencing, where access control is a low priority or non-existent) - means that the check is disabled. This means that anyone who is able can alter the security files without Secwin detecting. Only affects Access Control.
  Command-line disable (only recommended for sites using licencing, where access control is a low priority or non-existent) - means that you can disable the Security file check from a command line parameter of your choice. You would use this typically if a user cannot restore their security file from backup. Only affects Access Control.
• Security File Position - Set the default position for the security file. See also Locating the Security File.
• Default Language File - If you want to use a language file other than English, then put the name in here. See Also Translating Secwin windows.
• Language File Position - Set the default position of the Language File.

• Email Address - the address to use for CRC check requests (see corrupt Security files in the error messages section)
• Application Pin - See Application Pin Numbers in the User Guide.
• Encryption Key - See Using an encryption key in the user guide.
• Function Overrides - the names of the procedures in your application used for the various Secwin functionality:
  • SetAccess: Typically this is the SecwinSetAccess procedure (not the SecwinSetAllAccess window). This is called by Ctrl-F8.
  • ChangePassword: Typically this is the SecwinChangePassword procedure - called when a password change is required.
  • Login Procedure: Typcially this is the SecwinLoginScreen procedure - called when a login is required.
  • First User Proc: Typically this is the SecwinFirstUser procedure - called when no users exist and the first user must be entered.
  • Browse Users Proc: Typcially this is the SecwinBrowseOperators procedure - called to show operators for this application.
• Functions are in another application - For Multi-DLL applications, check this checkbox if the functions are in another DLL.
• Automatically map the Functions - this will create a module map in your global map for this dll for the procedures that you will require (like the SecwinSetAccess window and the SecwinChangePassword function). Most times you can leave this unchecked - as using the TXA will create the map for you.
• I'm using 9046 - only for Secwin users using Clarion 6.2 9046.
• Generate inc file with Access points everytime - this will generate an include file that Secwin makes use of to create the Access points list in the SetGlobalAccess window. Uncheck this if you don't need the AccessPoints generated.
• INC FileName - the name of the include file to contain the Access points (on the Global SetAccess window).
• Access Queue label - the label of the Access Q to contain the access points (see Creating your own Global SetAccess window for more details).
• Application Description - Defaults to the Unique Application Name. This will be the primary node of the access points tree (on the Global SetAccess window).
• Sort Access points in - This will enable you to set the order of the Access Points in the Access Points tree (on the Global SetAccess window). Template List order (the order that the access points are listed in the Control Restrictions list), Restriction Name order (alphabetical by the name of the access points' names), and Bit Position order (in order of the bit position of the access points).

Extension : MakeLogoScreen

Visible Effect to your App

If you add this extension to a screen then the screen will be displayed, but only in the background. this template is used in conjunction with the RunLogoScreen Extension

Purpose

This is an Extension template which can be added to a screen to make it a background screen. This background screen is ideal for displaying the application's current user, current license etc. This effect only works on MDI applications, and the screen must be an MDI child window screen. The best way to run this procedure is by using the supplied RunLogoScreen extension in your Main procedure.

Tip : If you have the MDI attribute clicked off by mistake then the window will float on top of all your other windows instead of going to the back.

Tip : Setting the border of the screen to None, and the Caption to blank and ensuring that the System attribute is off, improve the screen's look. You can also use the Center attribute on the Position tab when designing the screen to have the screen automatically center itself.

To Include in your App

1. Open your App in the usual fashion
2. Click on the Window procedure that you want to make a "background" window
3. Click on Extensions
4. Click on Add
5. ChooseMakeLogoScreen

Options

Extension : RunLogoScreen

Visible Effect to your App

This template calls your logo window, which makes the logo window visible.

Purpose

This template starts a thread with your MDI logo window.

To Include in your App

1. Open your App in the usual fashion
2. Click on your Main function
3. Click onExtensions
4. Click on Add
5. Choose RunLogoScreen Extension

Options

Extension : User Login Here

Visible Effect to your App

The user must enter a valid user code and password here before the screen will open. If you are not using AccessControl, you will still need...

Purpose

Use this extension wherever you want password protection. In the usual case, where the user logs in before running the Application, use this template extension on your 'main' function.

You can include any number of these extensions throughout your program. Each time one is encountered the user will be required to enter a valid user code and password in order to continue. In each section you can reset which users are operators, and which are supervisors.

When the function, in which you use this extension, is completed then the user is automatically logged out. The user then returns to the level, and accesses, they had before entering the function.

You can tell the program to activate licensing support at this time, and "get" a valid license.

You can include a "Super User" at this point. This user, although deletable, will re-appear in the browse users list every time a user logs in.

To Include in your App

1. Open the App in the normal fashion
2. Click on the procedure where you wish the login screen to appear
3. Click on theProperties button.
4. Click on Extensions
5. Click onAdd
6. Choose User Login Here from the list of available extensions

Options

Extension : User Screen Security

Visible Effect to your App

At runtime a supervisor can press a hotkey ( Ctrl F8 by default ), on this screen, and get a list of operators, along with the list of restrictions. By using the mouse he can toggle access rights to individual operators. Only users designated as Operators for this area of the App who are not in groups, and user group names, will be displayed on the list.

Purpose

Include this extension in a function if you wish to restrict operators, on an individual basis, from all, or part of, the function. This will automatically check each operator as he enters the function to check if access to the screen is permitted, and also to check if access to controls on the screen are allowed. You can specify up to 30 other controls, apart from the actual access to the screen, that the operator can be restricted from. The controls that are not accessible can be either disabled, hidden or set to read-only.

To Include in your App

1. Open the App in the normal fashion.
2. Point to the function you wish to protect.
3. Click on theProperties button.
4. Click on Extensions
5. Click onAdd
6. Choose User Screen Security from the list of available extensions

- OR -

Add the AutoPopulateUserScreenSecurity Global Extension template to your application.

Options

Extension: AutoPopulateUserScreenSecurity

This template will auto-populate the UserScreenSecurity template to all your procedures in your application (except source and process procedures). Once added to your application, do not remove from the application, otherwise all the UserScreenSecurity templates will be removed (from their respective procedures).

This template is not recommended for small single-EXE applications - but can be very useful in Multi-DLL applications.

Extension: CreateSecwinMenu

Note: This template can only be added to a frame with the UserLoginHere template added there.

This template will create a Security menu with the necessary Secwin menu items to enable the user to access Access Control and Registration windows, where applicable. It can only be added to a Frame procedure.

This template will control what items are visible (depending on what features you've selected). For example: If you have disabled licencing and registration, then the RegisterProduct item will not be displayed in the menu list. If you have selected to make Access Control optional, then only the Create First User item will be displayed. If you are not wanting to use Access Control at all, then you can disable the Create First User item.

• Menu for Security items - you can either add the items to an existing menu, or allow the template to create a new menu on the menu bar (entitled 'Security' by default).
• Existing Menu - allows you to select the menu that the Security items must be added to.
• Menu label - the text to be displayed on the created menu.
• Each item button - you can disable the item (using the Don't use this item checkbox), and override the default text for each item. For those items where the procedure to call is not stipulated on the Global Extension template, you can specify the procedure to call:
  • 'Change Login' item would typically be set to use the SecwinChangeLogin procedure.
  • 'Browse User Groups' item would typically be set to use the SecwinBrowseUserGroups procedure.
  • 'Set User Access' item would typically be set to use the SecwinSetAllAccess procedure (not the SecwinSetAccess procedure).
  • 'Register Product' item would typically be set to use the SecwinRegisterProduct procedure.

Extension : User Workgroup Filtering

Visible Effect to your App

Allows you to use the CWG variable in your browse filtering.

Purpose

This allows you to filter records from the browse based on the current user's workgroup. You can set the User's workgroup on the User Details Form, which is called from the Browse Users Screen. This template will create a variable called CWG (a long) which stores the current users workgroup. You can then use this variable in your browse filtering.

To Include in your App

1. Open the App in the normal fashion.
2. Point to the browse function you wish to filter.
3. Click on the Properties button.
4. Click on Extensions.
5. Click on Add.
6. Choose User Workgroup Filtering from the list of available extensions.
7. Click on the OK button.
8. Add your desired filter in the normal fashion.

Note : No actual filtering is done by this template. You are free to implement filtering in the normal fashion. This template simply defines, binds, and primes the CWG variable for your use.

Control : Register Product Controls

Purpose

This allows you to create a Register product window inside your application (as apposed to using the deprecated RegisterProduct window inside the Secwin DLL).

To Include in your App

Use the Template Utility provided to create a SecwinRegisterProduct window in your application.

Options in the template

See the Creating your own Product Registration window section for more details.

Code : Call Current

Visible Effect to your App

Allows the user to call the ds_CurrentName, ds_CurrentLogin or ds_CurrentLevel function and place the result on the status bar.

Purpose

By using this template is is easy to see, on the status bar, the currently logged in user. You can use any one of the user name, user login code or user level. You can also prefix your own text or variable before the result of the function call.

To Include in your App

1. Go to the Properties screen of your Main Menu procedure
2. ChooseEmbeds
3. Choose After Opening Window
4. Choose the Call_Current code template

Options

Code : Calling Current Counter

Visible Effect to your App

Allows the developer to display the current value left in the counter.

Purpose

Allows the developer to display the current value left in the counter. This is useful if you have a counter based license. the result is stored in a field, and you can display the field on a Window or a report. It makes use of the ds_CurrentCounter function.

To Include in your App

1. Add the Code template to an embed in your program. You can call this function from just about any local (not global) embed point.

Options

Code : Calling Current Expiry Date

Visible Effect to your App

Allows the developer to display the current value currently in the Expiry Date in the License

Purpose

This is useful if you want to display to the user the date on which the license will expire. It uses the ds_CurrentExpiryDate function.

To Include in your App

1. Add the Code template to an embed in your program. You can call this function from just about any local (not global) embed point.

Options

Code : Calling CurrentLicense

Visible Effect to your App

Used to Brand Windows and Reports with the name of the user who is the current owner of this copy of the program. You can also use the Call Get License Details template to get all the license details.

Purpose

This code template is designed to be attached to a report, or window. It creates a variable called ds_RegisteredCompany. It puts the name of the current License owner into the variable for you. You can then put the string onto your window, or report, and format it any way you like. It uses the function ds_CurrentLicence.

To Include in your App

1. Go to the Procedure you want to display the License name in
2. Click onEmbeds for the procedure
3. Choose an embed that is near the beginning of the procedure. The exact spot will vary depending on your template, but any embed that happens before the report starts printing is fine.
4. Click on the Insert button
5. Choose theCall_CurrentLicence code template.
6. Close the windows in the normal fashion.

Then go to your Report or Window structure and populate the new Local Data variable called ds_RegisteredCompany

Code : Calling CurrentlyLoggedIn

Visible Effect to your App

Allows the user to see the list of all the users currently logged into the system. Note that the network licensing features must be activated in order for this to work.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_CurrentlyLoggedInEx function.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. ChooseEmbeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_CurrentlyLoggedIn code template.
6. Close the windows in the normal fashion.

Code : Calling Change Login

Visible Effect to your App

Allows the user to call the Change Login Screen.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_ChangeLoginEx function. If you're going to use the built-in Secwin window then typically this would be called from a menu item. If you are going to make your own Change Login window then you would add this to the Ok button on your Change Login window.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. ChooseEmbeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose theCall_ChangeLogin code template.
6. Close the windows in the normal fashion.

Options

Code : Calling Change Password

Visible Effect to your App

Allows the user to call the Change Password Screen.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_ChangePasswordEx function. If you're going to use the built-in Secwin window then typically this would be called from a menu item. If you are going to make your own Change Password window then you would add this to the Ok button on your Change Password window.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. ChooseEmbeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose theCall_ChangePassword code template.
6. Close the windows in the normal fashion.

Options

Code : Calling Get License Details

Visible Effect to your App

Allows you to load all the current existing license details.

Purpose

This is typically used when you are creating your own Product Registration screen. It allows you to prime all your variables with the current values. It calls several of the functions including ds_CurrentLicence, ds_CurrentSerialNumber, ds_CurrentCopies, ds_CurrentCounter, ds_CurrentAppLevel, ds_CurrentExpiryDate and ds_CurrentOptional

To Include in your App

1. Add this to the Init method (in ABC templates) or to the After Opening Window embed point if you are using the Legacy templates.

Options

Code : Calling Lock Screen

Visible Effect to your App

Allows the user to call the Lock Screen Screen.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_LockScreen function

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. ChooseEmbeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose theCall_LockScreen code template.
6. Close the windows in the normal fashion.

Code : Calling Operator Browse

Visible Effect to your App

Allows the user to call the Operator Browse Screen.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_OperatorBrowse function with the appropriate parameters.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button. This control should be visible from all the security areas within your App, so you may need to add more than one control.
2. Click onActions for the control.
3. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose theCall_OperatorBrowse code template.
6. Close the windows in the normal fashion.

Code : Calling Register Product

Visible Effect to your App

Allows the user to call the Register Product Screen.

Purpose

This code template is designed to be attached to a menu item or button. It calls the ds_RegisterProductEx function with the appropriate parameters.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_RegisterProduct code template.

Options

Code : Calling RunAnotherExe

Visible Effect to your App

Allows the user to run another Secwin program, using the currently logged in user. The program being run must have the Allow Automatic Logins from other EXE's option clicked on.

Purpose

This code template is designed to allow you to run other programs, from within the current program, at the same time automatically logging in to the new program using the existing user's details. This template uses the ds_Run function.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_RunAnotherExe code template.

Options

6. Set the name of the program to run as well as any other parameters that the program may need.

Code : Calling Set Language

Visible Effect to your App

International language support.

Purpose

Allows you to change the language file which will be used when displaying any of the default Secwin windows. Makes use of the ds_SetLanguage function.

To Include in your App

1. Add a control somewhere in your program. Usually this control would take the form of a menu item in your main menu, but it could also be a button, or a toolbar button.
2. Click on Actions for the control.
3. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_SetLanguage code template.

Options

Code : Calling SetPin

Visible Effect to your App

None

Purpose

This function is not designed to be added to your main application - rather it is used on the developer machine to stamp dssw4 files with PIN numbers.

This code template stamps the dssw4 file with an Application PIN number. Pin numbers enhance application security be ensuring that only correctly "stamped" dssw4 files will be considered valid for the application. A full description of the PIN number concept, and when you would use this function, can be found in the User Guide in the section entitled Application PIN numbers. It uses the ds_SetPin function.

To Include in your App

1. Remember this function would not be used inside the Application you are intending to protect. Rather you need to create a separate utility. 2 examples of such utilities are shipped with Secwin. They can be found in the \Clarion\3rdparty\Examples\Secwin\UsingPin directory.
2. Add a control somewhere in your utility. This control could be a menu item in your main menu, or a button, or a toolbar button.
3. Click on Actions for the control.
4. ChooseEmbeds
5. Choose Control Event Handling , after generated code, Accepted.
6. Choose theCall_SetPin code template.

Options

Code : Get Activation Code

Visible Effect to your App

None

Purpose

This function is not designed to be added to your main application - rather it is used on the developer machine to generate Activation Codes. This template makes use of the ds_GetActivationCode function.

Used in registration programs, like the included Register example application. You feed the template the variables it needs and it returns a valid activation code. You can find the Register example in the \clarion\3rdparty\secwin\register directory

To Include in your App

1. Add the code template to a button.

Secwin Technical Reference

See Secwin Data Types for the Secwin Specific data types required by some of these functions.

ds_UserAllowed (long app,string calledby,long override,long pUser,<string pUserSite>)

This function enables the application to get the access rights for a specific user for a specific part of the program ( usually a screen.) The function is called using the ApplicationNumber as well as the FunctionName. The function returns a string, in which each character signifies that access has been granted or denied to a particular section. If the bit is set the access has been granted, if it is not set then access has been denied.

These accesses only apply to users designated as 'Operators' on the Operator Browse screen. You cannot limit the access of an user designated as a 'Supervisor'.

Returns

A string which can be character tested to determine the access rights that the user has been granted. These access rights are set by calling ds_ModifyAccessEx

See Also

ds_LoginUser, ds_ModifyAccessEx

Example

ViewVideo Procedure

window WINDOW('Caption'),AT(-1,2,185,92),SYSTEM,RESIZE,MDI
  BUTTON('Delete'),AT(68,28,,),USE(?DeleteButton)
  BUTTON('Change'),AT(127,35,,),USE(?ChangeButton)
  BUTTON('Cancel'),AT(74,53,,),USE(?CancelButton)
  BUTTON('Ok'),AT(17,25,,),USE(?OkButton)
  BUTTON('Print'),AT(19,51,,),USE(?PrintButton)
END
ThisAllowedString string(252)

  CODE
  ThisAllowedString = ds_UserAllowed (Application Number,'ViewVideo',0,0)
  if ThisAllowedString[1] <> '1' then return.
  OPEN(window)
  WindowOpened=True
  if ThisAllowedString[2] <> '1' then hide(?OkButton).
  if ThisAllowedString[3] <> '1' then hide(?ChangeButton).
  alert(DS_SECURITYKEY)
  ACCEPT

ds_BuildKeys ( [Locale] )

Use this function to rebuild the keys in the Security file. Actually the main reason for this function is to allow you to change the LOCALE settings for the file. When you change your LOCALE settings then you need to rebuild the keys in order for the new Locale to take effect.

Returns

Nothing

Example

NewLogin String(12)
NewPassword String(12)
  Code
  ds_BuildKeys ()
  ds_BuildKeys ('My.Env')

See Also

ds_Allowed (ApplicationNumber , FunctionName, Override)

This function enables the application to get the access rights for a specific user for a specific part of the program ( usually a screen.) The function is called using the ApplicationNumber as well as the FunctionName. The function returns a long ( although currently only the low 8 bits are supported ), in which each bit signifies that access has been granted or denied to a particular section. If the bit is set the access has been granted, if it is not set then access has been denied.

These accesses only apply to users designated as 'Operators' on the Operator Browse screen. You cannot limit the access of an user designated as a 'Supervisor'.

Returns

A Long which can be bitwise tested to determine the access rights that the user has been granted. These access rights are set by calling ds_SetAccess

See Also

ds_LoginText, ds_SetAccess 

Example

ViewVideo Procedure

window WINDOW('Caption'),AT(-1,2,185,92),SYSTEM,RESIZE,MDI
  BUTTON('Delete'),AT(68,28,,),USE(?DeleteButton)
  BUTTON('Change'),AT(127,35,,),USE(?ChangeButton)
  BUTTON('Cancel'),AT(74,53,,),USE(?CancelButton)
  BUTTON('Ok'),AT(17,25,,),USE(?OkButton)
  BUTTON('Print'),AT(19,51,,),USE(?PrintButton)
END
ThisAllowed long

  CODE
  ThisAllowed = ds_allowed (Application Number,'ViewVideo',0)
  if ~band(ThisAllowed,1) then return.
  OPEN(window)
  WindowOpened=True
  if ~band(ThisAllowed,2) then hide(?OkButton).
  if ~band(ThisAllowed,4) then hide(?ChangeButton).
  if ~band(ThisAllowed,8) then hide(?DeleteButton).
  if ~band(ThisAllowed,16) then hide(?PrintButton).
  alert(DS_SECURITYKEY)
  ACCEPT

ds_ChangeLoginEx (ApplicationNumber, [Login], [Password], [Options])

This allows another user to Login without quitting the application. The login screen will behave using the same options as was last passed to ds_LoginUser. This function behaves the same as the ds_LoginUser function and uses the Login and Password parameters in the same way.

If Options is set to 1 then the default Secwin screen will not be displayed. This is used when you have your own ChangeLogin screen.

Note that you can create your own ChangeLogin window to collect the Login and Password from the user, and pass them on to this function. In this way you can bypass the built-in Secwin window.

Returns

A Byte containing 0 if the operation was successful, or 1 if the login was unsuccessful.

Example

NewLogin String(12)
NewPassword String(12)
  Code
  ds_ChangeLoginEx (AppNum,NewLogin,NewPassword)

See Also

ds_LoginUser, Code : Change Login, Making your own Secwin windows

ds_ChangeUserEmailAddress (long app,long pUser,string pUserSite,string pPassword,string pEmailAddress,long options)

Allows a user to change their email address. Note: that only the person currently logged in can change their EmailAddress. In other words the Password field must match the password that the person currently logged in.

If Option is set to 1 then the Secwin warning messages will be suppressed.

Returns

A long containing 0 if the operation was successful, or one of the following error codes;

ds_InvalidUser - the user is not currently logged in.
ds_InvalidPassword - incorrect password supplied.
ds_CannotBeBlank - the EmailAddress supplied is blank (if the ds_CannotBeBlank is set in the options flag).

Example

case ds_ChangeUserEmailAddress(AppNum,GLO:CurrentUser,,Loc:Password,Loc:EmailAddress,ds_CannotBeBlank)
of ds_InvalidUser
orof ds_CannotBeBlank
orof ds_InvalidPassword
 !Error changing email address. The Email address was not changed for this user.
else
  message('EmailAddress changed successfully')
end

Note: You must use the UserID (a number) not the login (see ds_GetUserProperty).

See Also

ds_LoginUser, ds_GetUserProperty

ds_ChangePassword ()

Allows the user who is currently logged in to change his or her password. The user will be required to enter his existing password, and then his new password twice. There is only one password per user, regardless of the number of applications or security areas.

To build your own password window, use the ds_ChangePasswordExfunction.

Returns

Nothing

Example

NewPassword String(20)
OldPassword String(20)

  Code
  ds_ChangePassword(OldPassword,NewPassword)

See Also

ds_ChangePasswordEx, Code : Calling Change Password,Making your own Secwin windows

ds_ChangePasswordEx (AppNum, OldPassword, NewPassword, VerifyPassword, Options)

Allows a programmer to use his own ChangePassword screen, and call this function to update the password stored in the database. Note that only the person currently logged in can change their password. In other words the OldPassword field must match the password that the person currently logged in.

If Option is set to 1 then the Secwin warning messages will be suppressed.

Returns

A Byte containing 0 if the operation was successful, or one of the following error codes;

1 Incorrect Old Password
2 New password cannot be the same as old password
3 New Password and Verify Password don't match.
4 Password cannot be blank
6 Password must contain 6 Alpha and 3 Numeric Characters

This last requirement is enforced if the Force Long Password option on the Login extension is set.

Example

OldPassword STRING(12)
NewPassword STRING(12)
VerifyPassword STRING(12)

window WINDOW('Change Password'),AT(,,209,75),SYSTEM,GRAY,AUTO
  PROMPT('Old Password:'),AT(34,6),USE(?OldPassword:Prompt)
  ENTRY(@s12),AT(103,6,60,10),USE(OldPassword)
  PROMPT('New Password:'),AT(34,22),USE(?NewPassword:Prompt)
  ENTRY(@s12),AT(103,22,60,10),USE(NewPassword),PASSWORD
  PROMPT('Verify Password:'),AT(34,38),USE(?VerifyPassword:Prompt)
  ENTRY(@s12),AT(103,38,60,10),USE(VerifyPassword),PASSWORD
  BUTTON('&Ok'),AT(56,55,45,14),USE(?Ok)
  BUTTON('&Cancel'),AT(109,55,45,14),USE(?Cancel)
END

  Code
  open(window)
  accept
    if field() = ?Ok and Event() = Event:Accepted
      if ds_ChangePassword(AppNum,OldPassword,NewPassword,VerifyPassword,0) = 0
        post(event:closewindow)
      end
    end
  end
  close(window)

See Also

ds_ChangePassword, Code: Calling Change Password, Making your own Secwin windows

ds_CheckEncryptedActivationCodeEx (string pActivationCode,*ProductDetailsGroupType pProductDetails,string pSeedCode,long pAppNumber,Queue pLimitsQueue,long pOptions=0),string

ds_CheckEncryptedActivationCode (string pActivationCode,*ProductDetailsGroupType pProductDetails,string pSeedCode,long pAppNumber,Queue pLimitsQueue),string

This function allows you to verify an activation code (generated by the ds_GetEncryptedActivationCode function) - against a set of licence information. The set of licence information must match that set used by the ds_GetEncryptedActivationCode function exactly.

Returns:

The ExpiryDate of the licence (if the Activation Code check is successful).
-1 = Activation code has expired.
-2 = Activation code failure (the Activation code does not match the details in the ProductDetails and/or LimitsQueue)
-3 = Incorrect product (the Activation code is correct, but the product does not match the one that the Activation code was issued for).

Example

See the ds_GetEncryptedActivationCode example to set the details of the licence. These must match those that are used to generate the activation code.

   case ds_CheckEncryptedActivationCodeEx(ActivationCode,MyDetailsGroup,'MySeedCode',MyLimitsQueue,ds_OneTime)
   of 0 to ds_SecwinLastDate
     !Success - restart your application for the licence to take effect.
   of -1
     !The activation code is no longer valid.
   of -2
     !Activation code failure. The Activation code does not match the details specified. Please ensure that the details match exactly for the code to take effect.
   of -3
     !In correct product. The activation code used is not for this product.
   of -4
     !Activation code already used.
   else
     !Unknown activation code error.
   end

See also ds_GetEncryptedActivationCode

ds_CurrentAppLevel ( )

This is a Registration related function. It allows the programmer to get the current Application Level ( e.g. Demo, Lite, Standard etc) set in the current license. Don't confuse this function with ds_CurrentLevel which is an Access Control related function, and returns the Users current level.

Returns

A long containing the current Application Level. Valid values are 1 to 5. 1 is the lowest level (Demo) while 5 is the highest (Enterprise).

Example

Result Long

  Code
  Result = ds_CurrentAppLevel()

See Also

Code : Get License Details, Using Levels

ds_CurrentCopies ( )

Allows the programmer to get the number of Copies set in the current license.

Returns

A long containing the current number of copies.

Example

Result Long

  Code
  Result = ds_CurrentCopies()

See Also

Code : Get License Details, Using Network Copies

ds_CurrentCounter ( )

Allows the programmer to get the Counter set in the current license. This Counter is set when the activation code is generated, and used.

Returns

A long containing the current Counter value.

Example

Result Long

  Code
  Result = ds_CurrentCounter()

See Also

Code : Get License Details, Using Counters

ds_GetEncryptedActivationCode (long pActivationExpires,long pLicenceExpires,*ProductDetailsGroupType pProductDetails,string pSeedCode,Queue pLimitsQueue),string

This function generates an activation code to be used to licence your application at your user's site. This function would typically not be in your application, but in a separate application that you keep locally to generate activation codes. An example ships with Secwin that you can use to generate activation codes, or as this basis for your own application.

Returns

A string containing the activation code to register the application at the clients site (using the ds_CheckEncryptedActivationCode function).

Example

MyDetailsGroup   group(ProductDetailsGroupType),pre() .
MyLimitsQueue    queue(LimitsQueueType),pre().
ActivationCode   string(20)
  code
    MyDetailsGroup.SiteLimiter = '$$$$'
    MyDetailsGroup.CompanyName = 'Paying Company'
    MyDetailsGroup.Product     = 'MyProduct'
    MyDetailsGroup.LicenceType = 0        !Permanent
    MyDetailsGroup.Copies      = 5
    MyDetailsGroup.Level       = ds_ProfessionalLevel
    MyDetailsGroup.SerialNumber = '12345'
    MyDetailsGroup.OptionalModules = 0
    MyLimitsQueue.Description  = 'Default Counter'        !The old Secwin3 counter
    MyLimitsQueue.Limit        = 100
    MyLimitsQueue.LimitIsRelative = 1                     !Counter is relative - so add 100 to the existing number in the licence.
    add(MyLimitsQueue)
    MyLimitsQueue.Description  = 'Customers'              !Limit the customers entries to 100
    MyLimitsQueue.Limit        = 100
    MyLimitsQueue.LimitIsRelative = 0
    add(MyLimitsQueue)
    ActivationCode = ds_GetEncryptedActivationCode(today()+31,today()+365,MyDetailsGroup,'MySeedCode',MyLimitsQueue)

See also ds_CheckEncryptedActivationCode

 ds_UpdateUser (long App,ds_UserDetailsType pUserDetails,long pRequest)

Note: This function has replaced the superannuated functions: ds_ChangeUser, ds_InsertUser and ds_DeleteUser

Lets you insert a user, change a user's (or user group's) details, or delete a user in source code.

Returns

Example

MyDetailsGroup   group(ds_UserDetailsType),pre() .
  code
  MyDetailsGroup.Number = UserNumber
  MyDetailsGroup.SiteLow = NewSiteLow
         !We'll leave the other fields blank, as they don't need to be changed.
  case ds_UpdateUser(App,MyDetailsGroup,ChangeRecord + ds_NoMessages)  !We'll display our own message for errors that occur
  of 0   !Success
  of ds_ErrorInvalidUser
    message('Operator Not Found')
  of ds_ErrorUsedElsewhere orof ds_ErrorLastSupervisor orof ds_ErrorSuperUser
    !Not valid for ChangeRecord - only for deleterecord
  else
    !Negative value means a file error occured
    message('Error('&errorcode()&') Writing Record: ' & Error())
  end

ds_Users (UserQueue)

This function is included in the docs for backward-compatibility reasons. It should be considered as obsolete. The ds_UsersEx function should be used.

Structure

ds_UserQueue Queue,pre(_dsq)
Name            string(20)
Surname         string(20)
Login           string(12)
UserGroup      Long
               end

Purpose

This function fills in a queue all the users currently in the database. In other words by using this function you can get the logins and names of all existing users.

Returns

Nothing. The queue you passed now contains all the user details.

Example

ds_UserQueue     Queue,pre(_dsq)
Name                 string(20)
Surname             string(20)
Login               string(12)
UserGroup           Long
                   end

  code
  ds_Users (ds_UserQueue)

See Also

ds_InsertUserEx, ds_ChangeUser, ds_DeleteUser, ds_CurrentOperatorNumber

ds_CountUsers( SecurityAreaName)

Counts the number of users that have access to this Area. If you create your own login screen, then you will probably want to create your own FirstUser screen as well. This procedure lets you determine if the FirstUser fuinction needs to be called. 

Returns

long containing the number of users with Supervisor or Operator access.

Example

  code
  if ds_CountUsers(Clip(AppNameDesc) & ' | Main') = 0
    myFirstUser(Clip(AppNameDesc) & ' | Main')
  end

See Also

ds_InsertFirstUser

ds_CreSec

This function creates the security file. Typically it's called from inside a separate utility, but it can be called from inside your program. 

Care should be taken if you add this to your application as it can mean a serious breech of the security is possible.  For example a user might overcome the security simply by deleting the security file and running the program again. This is less of a problem if the Licensing features are enabled as the program will have to be re-activated before it will run.

The function won't empty, or overwrite, any security file which might exist already.

Returns

Nothing

Example

code
ds_SetOwner ('bobbybrown', 'washere')
ds_CreSec( )

See Also

Creating the Security File, Activate Security Extension, ds_SetOwner

ds_Crypt (TextString)

Allows you to perform simple encryption on a string. To decrypt the string you pass the encrypted string to ds_Crypt. This doesn't provide a very high level of encryption as no key is used, but it does prevent unsophisticated users from finding sensitive text on the disk.

Returns

A String containing the encrypted or decrypted string.

Example

Test   String(12)

  Code
  test = ds_Crypt('hello') ! now test contains the encrypted string
  test = ds_Crypt(test) ! now test contains the decrypted string

ds_ExportTables(byte pSelectDir=0)

Exports the Secwin tables to a portable format. Useful when you need to move the tables from one storage system to another (for example TPS to MSSQL).  The encrypted file is called dssw4.BIN and it will be created in the "Current directory". Use the ds_ImportFiles function to import the file.

Tip : It is recommended that this function is only called After the call to ds_LoginUser.

Tip : Use SETPATH to set the current directory, however it is recommended that you restore the current directory to the previous value after the export.

Returns

Nothing

Example

  Code
  ds_ExportTables()

SeeAlso

ds_ImportTables

ds_ImportTables(byte pSelectDir=0)

Exports the Secwin tables to a portable format. Useful when you need to move the tables from one storage system to another (for example TPS to MSSQL).  The encrypted file is called dssw4.BIN and it will be created in the "Current directory". Use the ds_ImportFiles function to import the file.

Tip : It is recommended that this function is only called After the call to ds_LoginUser.

Tip : Use SETPATH to set the current directory, however it is recommended that you restore the current directory to the previous value after the export.

Tip : Data from the import is added to the existing Secwin data. Duplicate records are automatically discarded. However this function is designed primarily to move complete Secwin data, and is not designed to merge Secwin data. While merges of multiple data files may be successful, no guarantee is offered in this regard.

Returns

Nothing

Example

  Code
  ds_ImportTables()

See Also

ds_ExportTables

ds_CurrentLastPasswordChange (ApplicationNumber)

Allows the programmer to get the date on which the password, for the logged in user, was last change. Useful for implementing your own "Force Password Change" feature when the built-in version is not flexible enough.

Returns

A long containing the date of the last password change in a Clarion standard date format.

Example

Result Long

  Code
  Result = ds_CurrentLastPasswordChange(AppNum)
  If Today()-Result > 7
    ds_ChangePassword(AppNum)
  End

See Also

ds_ChangePassword

ds_CurrentLevel (ApplicationNumber)

Allows the programmer to get the Level of the user who is currently logged on. This can be useful for displaying the login of the current user on the status bar etc.

Returns

A long containing the level of the user currently logged on. The returned value will be either DS_SUPERVISOR or DS_OPERATOR.

Example

CurrentLevel Long

  Code
  CurrentLevel = ds_CurrentLevel(AppNum)

See Also

ds_CurrentLogin, ds_CurrentName, ds_CurrentOperatorNumber, Code : Calling Current

ds_GetProperty (long ApplicationNumber,string pUserNumber,<string pUserSite>,string pProperty)

ds_GetUserProperty (long ApplicationNumber,string pUserLogin,<string pUserSite>,string pProperty)

Function Purpose

These function returns information pertaining to a user (or the current user). Depending on the property passed, will depend on the value returned (see the pProperty parameter).

Returns

ReturnValue      string(252)    !For Login, FirstName, LastName, EmailAddress, ExtraString
ReturnValue      long           !For DefaultAccess, Level, Number, WorkGroup, LastPasswordChange, ExtraLong
ReturnValue      cstring(1024)  !For FingerPrint1 and FingerPrint2

Note: If the user does not exist or there is an file error in obtaining the user's details, then a blank string (equates to 0 for a long) is returned.

Example

   ReturnValue      = ds_GetProperty(AppNum,0,,'FirstName') & ' ' & ds_GetProperty(AppNum,0,,'LastName')
   ReturnValue      = ds_GetUserProperty(AppNum,Login,,'FirstName') & ' ' & ds_GetUserProperty(AppNum,Login,,'LastName'
   case ds_GetUserProperty(AppNum,Login,,'Level')
   of ds_Operator
       !This is an operator
   of ds_Supervisor
       !This is a Supervisor
   of ds_NoAcccess
       !This user is disallowed from the application
   end
   case ds_GetUserProperty(AppNum,Login,,'DefaultAccess')
   of ds_AllAccess
       !This is user has all access to security areas by default, unless restricted.
   of ds_NoAcccess
       !This user is disallowed from the security ares by default, unless allowed.
   end

ds_CurrentExpiryDate ( )

Allows the programmer to get the current Expiry Date set in the current license. This Date is set when the activation code is generated, and used.

Returns

A long containing the current date in a Clarion standard date format.

Example

Result Long

  Code
  Result = ds_CurrentExpiryDate()

See Also

Code : Get License Details, Using Expiry Dates

ds_CurrentLicence ( )

Allows the programmer to get the name that this program has been licensed to as set in the current license. This value can be used in the product as a "Branding" technique. For example this value could appear on reports, on the MDI screen etc.

Returns

A string containing the company, or person, name of the registered user. This string can be a maximum of 40 characters long.

Example

result string(40)

  code
  result = ds_CurrentLicence()

See Also

Code : Get License Details, Branding on Reports, Branding Using Logo screens

ds_CurrentLicenceDetails ()

Purpose

This function returns all the licence details of the current licence used by the application.

Returns

A group containing the current licence information as follows:

Example

LicenceDetails  group(ProductDetailsGroupType),pre(LD) .

  code
    LicenceDetails = ds_CurrentLicenceDetails()
    message('Current licence details are:|' & |
            ' Company: ' & LD:CompanyName & '|' & |
            ' LicenceType: ' & LD:LicenceType & '|' & |
            ' Copies: ' & LD:Copies & '|' & |
            ' Level: ' & LD:Level & '|' & |
            ' SerialNumber: ' & LD:SerialNumber & '|' & |
            ' Dealer: ' & LD:Dealer)

ds_CurrentlyLoggedIn (Options)

This function requires the registration features to be active. Allows the user to see who else is logged on to the system. This is useful when you wish to ask people to quit the program because of insufficient licenses, or if you need to update the program on the server.

If the DS_DONTSHOWSCREEN option is used then the function will not open a screen showing the list of users.

Irrespective of the parameter, a comma delimited list of User Names is passed back from the function.

Returns

A comma delimited string containing the list of User Names currently on the system.

Example

List string(255)

  Code
  ds_CurrentlyLoggedIn()
  list = ds_CurrentlyLoggedIn (DS_DONTSHOWSCREEN)

See Also

Code : Calling Currently Logged In, Using Network Copies, ds_CurrentlyLoggedInEx

ds_CurrentlyLoggedInEx (LoggedInQueue)

Structure

LoggedInQueue       QUEUE,PRE(_dsqex)
Name                   STRING(255)
Reserved               STRING(255)
                    END

Purpose

This function requires the registration features to be active. It fills the supplied Queue with the names of all the other users who are logged onto the system.  This is useful when you wish to ask people to quit the program because of insufficient licenses, or if you need to update the program on the server.

In addition to the Queue being populated, a comma delimited list of User Names is passed back from the function.

This function is not designed to replace ds_CurrentlyLoggedIn, but rather to provide a method for getting the list of names in a Queue format. This is particularly useful if large numbers of users will be connected, and the string is not large enough for the whole list.

Returns

A comma delimited string containing the list of User Names currently on the system.

Note: The first item in the queue/string is the current user. This will mean that the user is duplicated in the queue of users. Don't forget to free the queue before calling the function, as the function will simply add to the queue.

Example

UserQueue            QUEUE,PRE(_dsqex)
Name                   STRING(255)
Reserved               STRING(255)
                     END
s                    STRING(255)

  code
  s = ds_CurrentlyLoggedInEx (UserQueue)

See Also

Code : Calling Currently Logged In, Using Network Copies, ds_CurrentlyLoggedIn

ds_CurrentOptional ( )

Allows the programmer to get the optional modules that this program has been licensed to as set in the current license.

Returns

A long, where each bit represents an optional module. You can test for a specific optional module by BANDing the result with one of the DS_OM1 to DS_OM30 equates.

Example

result long
Optionalmodule1 byte
OptionalModule2 byte

  code
  result = ds_CurrentOptional()
  if band(result,DS_OM1) then OptionalModule1 =1.
  if band(result,DS_OM2) then OptionalModule2 =1.

See Also

Code : Get License Details, Using Optional Modules

ds_CurrentSerialNumber

Allows the programmer to get the Serial number as set in the current license.

Returns

A String (20) containing the Serial Number.

Example

SerialNumber   String(20)

  code
  SerialNumber = ds_CurrentSerialNumber()

See Also

Code : Get License Details

ds_DecrementCounterEx(long pDecrementBy)

Removes pDecrementBy (normally 1) from the value stored in the License. This is used when selling your program by number of runs, or number of reports, or something like that.

Returns

0 if successful. 1 if failed. The function will fail if the counter is already set to 0.

Example

Result  Long

  Code
  result = ds_DecrementCounterEx(1)
  If result = 0 then return.

See Also

Using Counters
ds_CheckCounter

ds_CurrentLogin (ApplicationNumber )

Allows the programmer to get the Login Code of the user who is currently logged on. This can be useful for displaying the login of the current user on the status bar etc.

Returns

A string containing the login code of the user currently logged on. The maximum length of the string is 12 characters.

Example

CurrentLogin string(12)

  Code
  CurrentLogin = ds_CurrentLogin (AppNum)

See Also

ds_CurrentLevel, ds_CurrentName, ds_CurrentOperatorNumber, Code : Calling Current

ds_CurrentName (ApplicationNumber )

Allows the programmer to get the Name of the user who is currently logged on. This can be useful for displaying the name of the current user on the status bar etc.

Returns

A string containing the name of the user currently logged on. The maximum length of the string is 40 characters.

Example

currentname string(40)

  code
  currentname = ds_CurrentName(AppNum)

See Also

ds_CurrentLevel, ds_CurrentOperatorNumber, ds_CurrentLogin, Code : Calling Current

ds_CurrentOperatorNumber (ApplicationNumber)

Allows the programmer to get the Operator Number of the user who is currently logged on. This matches the number returned in the ds_UsersEx function.  You can use this number (which is unique for each operator) to link your own user file to the Secwin user file.

Returns

A long containing the operator number  of the user currently logged on.

Example

CurrentOperator Long

  Code
  CurrentLevel = ds_CurrentOperatorNumber(AppNum)

See Also

ds_UsersEx, ds_CurrentLevel, ds_CurrentLogin, ds_CurrentName, Code : Calling Current

ds_CurrentUserGroup (ApplicationNumber)

This function has been deprecated in Secwin 4 for the following reason:

You'll need to alter your code so that it loops through the UserGroups queue and checks each value to see whether that user belongs to the user group (rather than checking a single value).

ds_CurrentWorkGroupEx (ApplicationNumber)

Allows the programmer to get the Workgroup of the user who is currently logged on. The users' Workgroup is set on the users form by a Supervisor. Workgroups are a way of grouping users for browse filter purposes.

Returns

A long. The number returned is the number entered in on the User form.

Example

CWG long

  code
  CWG = ds_CurrentWorkGroup (AppNum)

See Also

Work Groups, ds_GetWorkGroupEx

ds_GetAccessEx (ApplicationNumber, CalledBy, User )

This function returns the access rights for a particular user, for a particular procedure in the application. If the CalledBy parameter is set to LEVEL then it returns the user's Level.  This function is provided primarily so you can build your own SetAccess window.

Returns

A Long, containing the access rights for that user, for that particular screen. This is basically the number that has been set using the ds_SetAccessEx function. If the CalledBy parameter is set to LEVEL then it returns one of DS_NOACCESS, DS_OPERATOR or DS_SUPERVISOR.

Example

See the included Splash example for an example of a SetAccess window.

See Also

ds_Allowed, ds_SetAccessEx

ds_CurrentName (ApplicationNumber )

Allows the programmer to get the Name of the user who is currently logged on. This can be useful for displaying the name of the current user on the status bar etc.

Returns

A string containing the name of the user currently logged on. The maximum length of the string is 40 characters.

Example

currentname string(40)

  code
  currentname = ds_CurrentName(AppNum)

See Also

ds_CurrentLevel, ds_CurrentOperatorNumber, ds_CurrentLogin, Code : Calling Current

 ds_CheckCounter (string pCounter,long pDecrementBy=0,long pOptions=0),long

Removes pDecrementBy from the pCounter value stored in the License. This is used when selling your program by number of runs, or number of reports, or something like that. If the pCounter is blank, then the Default Counter will be used.

This function replaces the old ds_DecrementCounterEx and ds_DecrementCounter functions.

Returns

The Counter value before decrementing if successful. 0 if the Counter is 0 and therefore no more records/reports/procedures are permitted on this licence. If the function fails then nothing is removed from the counter. If pDecrementBy is 0, then the Counter is not altered, but simply returned as is.

Example

See Also

Using Counters

ds_DeleteUser (ApplicationNumber , Login)

Allows the programmer to delete a user in Source code. Users that are used in other applications which share this file cannot be deleted. (Rather set their Level to NoAccess using the ds_ChangeUser function). If the user is the last Supervisor for an application, and other Operators exist, then he can't be deleted. 

Returns

0 if successful. 
1 if the operator doesn't exist. 
2 if he's the last Supervisor. 
3 if the user is used in another application
4 if some file-access-error prevented the delete. Use ERRORCODE() to get the actual error.

Example

  code
  execute ds_DeleteUser(App,LoginCode)
    message('Operator Not Found')
    message('Can''t delete last supervisor')
    message('Operator used by another program')
    message('Unable to delete operator: ' & error())
  end

See Also

ds_InsertUserEx, ds_ChangeUser

ds_GetAccess44 (long App,string CalledBy,Long User,string pUserSite)

This function returns the access rights for a particular user, for a particular procedure in the application. If the CalledBy parameter is set to LEVEL then it returns the user's Level. 

Returns

A Long, containing the access rights for that user, for that particular screen. This is basically the number that has been set using the ds_ModifyAccessEx function. If the CalledBy parameter is set to LEVEL then it returns one of DS_NOACCESS, DS_OPERATOR or DS_SUPERVISOR.

Example

if ds_GetAccess4(App,'Level',UserNumber,'$$$$') = DS_OPERATORString then
  !Do stuff for operators in here.
end
Access = ds_GetAccess4(App,CalledBy,UserNumber,'$$$$')

See Also

ds_UserAllowed, ds_ModifyAccessEx

ds_GenerateActivationCode ( )

Opens a screen that lets you generate an activation code. You wouldn't normally include this function in an application. The Register.App example calls this function so that you can generate unique activation codes based on your clients name etc. The example can be found in the \Clarion\3rdParty\Examples\Secwin\Register directory.

Returns

Nothing

Example

  code
  ds_GenerateActivationCode()

See Also

ds_GetActivationCode, Some Activation Code Secrets

ds_GetActivationCode ( Product, Company, SerialNumber, Copies, Level, Optional, ExpiryDate, Counter, SeedCode )

Takes all the required parameters and returns an activation code. This function is provided so that you can design your own activation code generation procedures. For an example of using this function see the Register.App demo application This example is in the \clarion\3rdparty\examples\secwin\register directory.

This function is not typically called in the programs that you distribute.

Returns

A String of length 20 containing the Activation code.

Example

AC String(20)
  Code
  AC = ds_GetActivationCode ('App','Comp','001',5,3,0,today()+30,0,1234)

See Also

ds_GenerateActivationCode, Some Activation Code Secrets

ds_GetDriveSerialNumber ( [Drive] )

Used to get the Serial Number of the Hard Drive. This can then be used as the program's serial number. By comparing the two numbers you can detect when the data has been moved from one hard drive to another.

Returns

Ulong containing the Serial Number

Example

Code
If ds_GetDriveSerialNumber() <> ds_CurrentSerialNumber()
   message('I'm an unhappy program.')
   return
End

ds_GetWorkGroup (ApplicationNumber, OperatorNumber)

Obsolete. Use ds_GetWorkGroupEx instead.  ds_GetWorkGroup returns a Short not a Long.

ds_GetWorkGroupEx (ApplicationNumber, OperatorNumber)

Allows the programmer to get the Workgroup of another user. The users' Workgroup is set on the users form by a Supervisor. Workgroups are a way of grouping users for browse filter purposes.

Returns

A long. The number returned is the number entered in on the User form.

Example

CWG short

  code
  CWG = ds_GetWorkGroup (AppNum,1)

See Also

Work Groups, ds_CurrentWorkGroup

ds_InsertFirstUser(SecurityAreaName,Firstname,Lastname,LoginCode,Number)

If the login to your program is not optional, then an issue arises if no user has access to the program. At this point Secwin insists that either an existing user (who currently has No Access) is granted access to the system, or a new user is created. In either case the user will be granted Supervisor status.

Returns

0 = Success. Otherwise Failure.

Example

  Code
  If choice(?list1) < 0 
     get(q,choice(?list1))
    ds_InsertFirstUser(AppName,FirstName,LastName,LoginCode,q.Number)
  Else
    ds_InsertFirstUser(AppName,FirstName,LastName,LoginCode,0)
  End

See Also

ds_CountUsers

ds_InsertUser( AppNum, FirstName, LastName, LoginCode, InitialAccess, Workgroup, Level)

This function is obsolete. It's exactly the same as calling ds_InsertUserEx with the UserGroup parameter set to 0. It is included here for backward compatability reasons.

ds_InsertUserEx( AppNum, FirstName, LastName, LoginCode, InitialAccess, Workgroup, Level, UserGroup)

Lets you add a user (or user group) to the system in source code. As in the screen version the user's initial password is set the same as his login code. If the user exists, or if one of the parameters is blank, then the function will fail.

If you are adding a User Group then the WorkGroup field is ignored, and the FirstName field contains the User Group Name (eg Sales). The LastName parameter should contain a space and the FirstName value. The Login code should be blank.

Returns

0 = successful. 
1 = Either No FirstName, no LastName, no LoginCode, or InitialAccess not set to 0 or 1.
2 = An error adding the operator to the File (use Error() and ErrorCode() for details)

Example

Code
ds_InsertUserEx (AppNum, 'Bill', 'Gates', 'BG',1,0,DS_OPERATOR,0)
ds_InsertUserEx (AppNum, 'Sales', ' Sales','',1,0,DS_OPERATOR,-1)

See Also

ds_UsersEx, ds_ChangeUser, ds_DeleteUser

ds_LicenceOk( RqdLevel, RqdModules, Options)

Checks the users current license and returns a value to tell you if it passed or failed the check. Equates have been defined for the different optional modules, namely DS_OM1 thru DS_OM30. You can modify the behaviour by using the options parameter with one or more of the following values.

DS_NOWARN : By default Secwin displays a warning to the user when one of these checks fails. By including this option no warning is displayed.

DS_NODATECHECK : This ignores the checks for errors 3 and 4.

DS_NONETWORKCHECK : This ignores the check which could return error 5.

DS_MULTIDATA : This ignores the check that could return error 7.

Returns

0 if successful.
1 if the current license level is not sufficient.
2 if the current license  has expired
3 if the current PC date is less than the date of a previous use of the license.
4 if the current Pc date is more than 2 years later than the previous use of the license.
5 if too many network users are logged in.
6 if the current licence's optional modules are not sufficient.
7 if the date and time of the dssw4 file goes backwards. (suppress this check with DS_MULTIDATA)

Example

Result long

  Code
  Result = ds_LicenceOk(1,0,0)
  Result = ds_LicenceOk(3,DS_OM1,DS_NOWARN)
  Result = ds_LicenceOk(5,DS_OM1 + DS_OM8,DS_NOWARN + DS_NODATECHECK)

ds_LockScreen ( ApplicationNumber )

Allows the user who is currently logged in to lock the application while being away from the terminal temporarily. The screen is blacked out and the user must enter their password before the application will continue. Note that the machine is not locked as the Windows task manager is still active. The application can also be terminated using the task manager.

Returns

Nothing

Example

Code
ds_LockScreen (AppNum)

See Also

Ancillary User Functions, Code : Calling Lock Screen

 ds_LoginUser (ds_UserLoginOptions pUserLoginOptions,*long pUser)

Possible Options

DS_DEFAULT (0) : Default behaviour. A login is definitely required, and the password is case sensitive. Automatic logins are not allowed, and unlimited login tries are accepted.

DS_CASESENSITIVITYOFF : If this flag is present then the User password is not case sensitive.

DS_THREETRIES : Limits the number of login attempts to 3 before the program automatically aborts the login attempt.

DS_USECURRENTLOGON : Allows this application to accept automatic login attempts, using the ds_Run function.

Function Purpose

Allows a user to login to the program, or program area. A window will be opened allowing the user to enter a user code and a password. If there are no users defined for this application then one of the following two actions will occur.

1. If security is not optional then you will be asked to either assign an existing user to this area as a Supervisor, or to add a new user as a Supervisor. If you add a new user then the initial password is the login code.

2. If security is optional then no window will be opened and the user will automatically be given the Supervisor level.

If the DS_USECURRENTLOGON flag is set then the function will attempt to log the user in using the same login code and password of the calling program. The calling program uses the ds_Run function (or template) to run this program.

Returns

The Application Number (long).
This number is used by other functions so it must be stored, a global, non-threaded long is the perfect storage vessel. If the number returned is 0 then the login was unsuccessful and appropriate action should be taken.

Advanced

If you have multiple login areas within one application then store the application number (AppNum) in a queue, adding the new AppNum to the top of the queue when successfully logging in, and removing it when logging out. This ensures that AppNum always points to the current user area.

Calling ds_LoginUser automatically logs out the existing user for this instance of the area, if one exists. In other words calling ds_LoginUser (SecurityAreaName, x) causes an implicit ds_LogoutUser (ApplicationNumber) - i.e. a logout of the same area - to be called before ds_LoginUser. If no user is logged in then ds_LogoutUser ignores the request.

Example

AppNum long
MyUserLoginOptions group
AreaName             string(252)
User                 string(252)
Password             string(252)
Options              long
                    end
MyUser              long
  Code
  MyUserLoginOptions.AreaName = 'MyApplication | Main'
  MyUserLoginOptions.User = 'Geoff'
  MyUserLoginOptions.Password = 'MyPassword'
  MyUserLoginOptions.Options = 0   !Use the equates listed above.
  AppNum = ds_LoginUser (MyUserLoginOptions , MyUser)
  if AppNum = 0
    ! login was unsuccessful
    return
  End

See Also

ds_Logout, Extension : User Login Here, Login and Password Access Control, Making your own Secwin windows

ds_LogoutUser (long ApplicationNumber,long pUser)

Allows a user to logout of an application, or application area. The user will have to re-enter his login code and password before he can re-enter the part of the application protected by the password.

It is not necessary to Logout if the program is being terminated.

Returns

0 if successful. 1 if unsuccessful.
If the function returns 1, then the user was not logged in to the application.

Example

AppNum long
Result long

  code
  AppNum = ds_LoginUser ('Video.Exe', ds_DEFAULT,'','')
  if AppNum = 1
    ! login was unsuccessful
    return
  End

  < function code goes here >

  result = ds_LogOut (AppNum)
  return

See Also

ds_LoginUser

ds_OperatorBrowse (ApplicationNumber)

Allows you to Browse the users for this Application or Security area. Only Supervisors have access to this screen. A Supervisor must use this function to add, edit or remove other Supervisors or Operators.

Returns

Nothing

Example

AppNum long

code
ds_OperatorBrowse (AppNum)

See Also

Operator Browse and Form, User Groups, Work Groups

ds_RegisterProductEx ( Product, Seed, Options, Company, SerialNumber, Copies, Level, Modules, Activation code, Counter)

This function is used to change the users current license levels. 

NOTE: This function relies on the existance of a licence already. It merely changes the existing licence. If you are handcoding the call, then you need to first call ds_UseLicence in order to create an initial licence.

The product parameter is set with the name of the product. This is usually hard coded into an application, and cannot be changed on this screen.

The seed code is used so that other developers cannot generate activation codes for your applications. This is normally hard coded into the application, and isn't seen by the end user.

The options parameter allows you to change the way the screen behaves.
If it contains any of the DS_LVL equates (DS_LVL1 to DS_LVL5) then that level will not be displayed on the screen. So you can hide the Professional and Enterprise options by including DS_LVL4 + DS_LVL5 in the options parameter.

If it contains any of the DS_OM equates (DS_OM1 to DS_OM15) then those optional modules will not appear. So to hide optional modules 13 thru 15 you would include DS_OM13 + DS_OM14 + DS_OM15 in the options parameter. If this parameter includes DS_OM16 then all optional modules from 16 to 30 are hidden.

If it contains the DS_DONTSHOWSCREEN parameter then the screen will not be opened. In this case you MUST pass all the correct values, including the activation code, to the function. This is available so that you can draw your own RegisterProduct screen. You should then check the value returned to make sure the call was successful.

If it contains DS_RELATIVECOUNTER then any value in the Counter field will be ADDED to the user's current Counter value. Use this in situations where you are basically trying simply to increment the number stored in the counter at the client.

If it contains DS_ONETIME then the activation code can only be entered once. If it is entered a second time it will fail. This prevents a user from entering a code, using up the Counter, and re-entering the same code (within the 7 day window).

Using the company, serial number, copies, level, modules and activation code parameters you can prime each of the values on the screen. If you omit any of these parameters then they will default to their current value.

Returns

0 if successful, 1 if Invalid Activation code.

Example

code
ds_RegisterProduct('Wonderprog',12345678,0)
ds_RegisterProduct('Wonderprog',12345678,DS_LVL4+LVL5)
ds_RegisterProduct('Wonderprog',12345678,DS_LVL4+LVL5+DS_OM15)

See Also

Code : Calling Register Product, Overview of Licensing, Making your own Secwin Windows

ds_UserRun (long ApplicationNumber,long pUser)

Allows you to launch another Secwin enabled EXE, performing an automatic login using the currently logged in user.

In other words, App A can use this function to run App B, at the same time passing App B the login code and password of the current user. App B will automatically log the person in.

In order for this to occur App B MUST have the login option DS_AUTOLOGON bit set. On the Login User Here template this option is referred to as "Allow automatic login's from other EXEs".

Returns

A string which needs to be included as a parameter in the Clarion "Run" statement.

Example

code
  run ('ProgName ProgParam ' & ds_Run (AppNum))

See Also

Code : Run Another Exe, Secwin Examples

ds_LoadLicenceFromXML(*ProductDetailsGroupType pDetailsGroup,*queue pLimitsQueue,string pXMLFile,<long pXMLStringLen>),long

This procedure allows Secwin to import licence details from either an XML file or a string in XML format (if the data is already loaded into a string).

Returns

long - 0 for success, otherwise an error occurred.

Example

See Secwin Data Types

ds_SaveLicenceToXML (*ProductDetailsGroupType pDetailsGroup,*queue pLimitsQueue,<string pXMLFile>,<ds_SecwinXMLString pSecwinXMlString>,<SaveLicenceToXMLOptionsGroupType pOptions>),long

This procedure allows Secwin to export licence details to either an XML file or a string in XML format (if not required to save directly to a file).

Note: If you are saving to an XML string, then you must dispose the string after using it (see the example code below)

Returns

long - 0 for success, otherwise an error occurred.

Example

SecwinXMLString group(ds_SecwinXMLString) .
  code
      !Here's an example of how you would create an XML licence string:
    if ds_SaveLicenceToXML(REG:CodeGroup,Queue:Browse,,SecwinXMLString) .
      !Do code using XML string such as:
    MyString = SecwinXMLString.bin     !The bin item in the group contains the contents of the string.
    MyStringLen = SecwinXMLString.len  !The len item in the group contains the length of the string
    dispose(SecwinXMLString.bin)       !You must dispose the string after using it.

      !Here's an example of how you would create an XML licence file:
    if ds_SaveLicenceToXML(REG:CodeGroup,Queue:Browse,clip(REG:CompanyName) & '_' & clip(REG:Product) &'.xml') .

See Secwin Data Types ; ds_MakeValidFileName

This procedure returns a valid filename that the ds_SaveLicenceToXML function will use to create the xml file for the licence details. You can then use this filename to handle the file that the ds_SaveLicenceToXML function creates.

Returns

string - contains the pFileName with invalid dos filename characters replaced with '_'

Example

    if ds_SaveLicenceToXML(REG:CodeGroup,Queue:Browse,ds_MakeValidFileName(clip(REG:CompanyName) & '_' & clip(REG:Product) &'.xml')) .

See Secwin Data Types ; ds_SaveLicenceToXML

ds_SecwinMakeover (MakeoverObject)

This procedure allows the Secwin screens to support CapeSoft's Makeover accessory. The Makeover object is created by the Exe, and then this function is used to pass a pointer to the object, to the Secwin DLL.  Note that Makeover is not required in order for Secwin to work properly. 

Returns

Nothing. 

Example

code
  ds_SecWinMakeover(ThisMakeover)

See Also

ds_SecwinMessage (MessageName)

This function gets, translates, and displays one of the common Secwin error messages. 

Valid message names are

Returns

Nothing. 

Example

code
  ds_SecWinMessage('AccessRestricted')

ds_ModifyAccessEx (ApplicationNumber ,ScreenName, Options)

This screen is normally called from within a specific function in order to change the access levels for the different operators, for that screen. Only Supervisors have access to this function. The access levels are retrieved using the ds_UserAllowed function. ds_ModifyAccessEx is normally invoked by pressing a hotkey. This hotkey is normally stored in the DS_SECURITYKEY equate. By default this key is Ctrl-F8. The function can however be called in almost any manner, for example by using a button on the window.

The Options parameter string contains all of the access options for the calling function, as you want them to be displayed on the ds_ModifyAccessEx browse box.

Returns

Nothing

Example

ViewVideo procedure

  code

  < normal opening window code etc goes here >

  alert(DS_SECURITYKEY)
  accept
    if keycode() = DS_SECURITYKEY
      ds_ModifyAccessEx (AppNum,'ViewVideo','Access|Delete|Print')
    End
    < rest of accept handling goes here >
  End

See Also

Set Access Rights Screen

ds_SetAccess (ApplicationNumber ,ScreenName, Options)

This screen is normally called from within a specific function in order to change the access levels for the different operators, for that screen. Only Supervisors have access to this function. The access levels are retrieved using the ds_Allowed function. ds_SetAccess is normally invoked by pressing a hotkey. This hotkey is normally stored in the DS_SECURITYKEY equate. By default this key is Ctrl-F8. The function can however be called in almost any manner, for example by using a button on the window.

The Options parameter string contains all of the access options for the calling function, as you want them to be displayed on the ds_SetAccess browse box.

Returns

Nothing

Example

ViewVideo procedure

  code

  < normal opening window code etc goes here >

  alert(DS_SECURITYKEY)
  accept
    if keycode() = DS_SECURITYKEY
      ds_SetAccess (AppNum,'ViewVideo','Access|Delete|Print')
    End
    < rest of accept handling goes here >
  End

See Also

Set Access Rights Screen

ds_SetAccessEx (ApplicationNumber, CalledBy, User, Rights )

This function sets the access rights for a particular user, for a particular procedure in the application.  This function is provided primarily so you can build your own SetAccess window.

Returns

Nothing

Example

See the included Splash example for an example of a SetAccess window.

See Also

ds_Allowed, ds_GetAccessEx

ds_ModifyAccessEx (long App,string CalledBy,Long User,string UserSite,string Rights,long pOperation=ds_ReplaceExistingAccess,long pAccessIsString=0)

This function sets the access rights for a particular user, for a particular procedure in the application. 

Returns

Nothing

Example

ds_ModifyAccessEx(App,CalledBy,UserNumber,'$$$$', NewAccessString,,1)   !Replace the existing access rights
ds_ModifyAccessEx(App,CalledBy,UserNumber,UserSite,4,1,-1)  !Force the user's access to be on for group 4 of the CalledBy area.
ds_ModifyAccessEx(App,CalledBy,UserNumber,UserSite,all('1',252),0,1)  !Force the user's access for all groups on this CalledBy area to NO ACCESS.

See Also

ds_UserAllowed, ds_GetAccess4

ds_SetDefaultFontEx(Face, Size, Color, Style, CharSet)

This function allows you to set the font that Secwin will use on it's screens. If you call the function with no parameters then the standard Windows Font Dialog box will be called so that the user can select the font.

Note: that only versions of Clarion 5.5 and later support CharSets. In the previous versions of Clarion, the Charset will be ignored.

Returns

Nothing

Example

code
ds_SetDefaultFont('Arial',10,Color:Black,Font:Regular)

See Also

Extension : User Login Here

ds_SetLanguage (LanguageFileName)

Allows you to adjust the text which appears on the Secwin screens. This is used to translate the native English of the Secwin screens into other languages. Note that this can be called from before or after the user logs in. If this is called before the user logs in then the settings for the language file in the various ini files will be ignored.

Returns

Nothing

See Also

User Guide : Internationalization support

Example

AppNum long

code
ds_SetLanguage ('Spanish.Irf')

See Also

Code : Calling Set Language, Translating Secwin Windows

ds_SetLogo (LogoFileName, CallbackFunctionAddress)

Allows you to change the logo that appears on all of the Secwin screens.

Returns

Nothing

Example

code
ds_SetLogo('c:\logo.ico',0) ! use logo in root directory
ds_SetLogo('logo.ico',0) ! use logo in current directory

See Also

Changing The Logo

ds_SetOwner (string Owner1, string Owner2)

This function allows you to set the Owner attributes for the Security, and License Files. This function is required to support the alternative file drivers. when you use the Topspeed driver (the default setting) then the owner variables are set internally, and this function has no effect. If you are using one of the other drivers, then set the owner using this function.

Returns

Nothing

Example

code
ds_SetOwner ('bobbybrown','washere')   !For flat files
ds_SetOwner ('SQLConnection,SQLDataBase,SQLUser,SQLPassword','/MultipleActiveResultSets=1')   !For SQL files

See Also

ds_CreSec, Activate Secwin Extension 

ds_SetPath ([Path], [LanguageFile], [LanguagePath])

Allows you to programmatically set the location of the Secwin support files, including the dssw4 file and the language file or language path. They specifically override the PATH, LANGUAGEFILE and LANGUAGEPATH settings as they appear in the Secwin.Ini file.

If any of the above parameters are omitted then the usual methods (ie INI file & defaults) are used to determine the position of those files.

For more information on the Language files and paths read the section in the User Guide on Translating Secwin Windows . 

Note : This function can only be called once, and must be called Before any other Secwin functions. Therefore it is recommended that you add this function, if required, to your Global Program Setup embed point.

Returns

Nothing

Example

code
ds_SetPath('c:\')
ds_SetPath('HERE')
ds_SetPath('HERE','Dutch.Irf','EXEDIR')

See Also

Translating Secwin Windows

ds_SetPin (SecurityAreaName, PinNumber)

Used to stamp the dssw4 file with a valid pin number. You would not normally do this from inside an application. The SetPin and HardPin examples use this function. The examples can be found in the \Clarion\3rdparty\Examples\Secwin\UsingPin directory.

Returns

Nothing

Example

code
ds_SetPin('Bobs App',12345678)

See Also

ds_UsePin, Pin Numbers, Extension : Activate Secwin Features

ds_SetSuperUser (LoginCode)

Use this function to set a user as a Super User. Note that this does NOT add a user, if the user doesn't exist then the function does nothing.

Returns

Nothing

Example

code
ds_SetSuperUser ('demo')

See Also

ds_UsersEx, ds_InsertUserEx, ds_ChangeUser, ds_DeleteUser, Extension : User Login Here, Super Users

ds_UseLicence (ProductName, ApplicationNumber,LicenseName, Options)

In order to enable the copy protection, and remote activation, features which Secwin can add to your application, you use Licenses. Somewhere near the beginning of your application (usually just after calling the ds_LoginUser function) you make a call to ds_UseLicence. A license is then sought, and held for the duration of the program. The license is automatically released when the program terminates (in whatever manner) or if the computer is switched off.

If no licenses exist then one will automatically be created. This created license will have a level of 'Demo' (level 1) and an automatic expiry period of 30 days. Your user can then change this license to their requirements when you supply hem with the necessary activation code. If you do not want the 30 day demo period then include the DS_NODEMO switch in the options parameter.

Although you can call this function at any time it is best to do it just after the call to ds_LoginUser as you will then be able to supply the ApplicationNumber parameter. This allows Secwin to put the name of the current user inside the license file so that others can see which users are currently using the program.

You can override the default behavior of checking network licenses (i.e. the user will have an effective "site license") by using the DS_NONETWORKCHECK switch in the options parameter.

Note: that no checking of the license occurs at this point. To check the license, especially the Expiry dates or application level, use the ds_LicenceOk function.

Returns

Nothing

Example

AppNumQueue Queue
AppNum         Long
              End

  Code
  AppNum = ds_LoginUser('Video.Exe',DS_DEFAULT,'','')
  if AppNum = 0
    ! login was unsuccessful
    Return
  End
  Add(AppNumQueue,1)
  ds_UseLicecnce('Amazing Wonderful Program',AppNum,'AWP',DS_NODEMO)

See Also

Overview of Licensing

ds_UsePin (SecurityAreaName,AppPinNumber)

This function allows you to "stamp" a dssw4 file as being valid. Without a pin number the user can simply delete the dssw4 file, and re-create an empty one using CRESEC25. This use of Pin numbers requires however that the dssw4 file be stamped with the correct pin number before it will be considered valid.

Returns

Nothing

Example

code
ds_UsePin (AppNameDesc,12345678)
ds_LoginUser( AppNameDesc, ds_Default,'','')

See Also

ds_SetPin, Pin Numbers, Extension: Activate Secwin Features

ds_UsersEx (Appnum,UserQueueEx)

Note: In Secwin4 this function has changed somewhat, because a user can now belong to multiple user groups. In order to get a list of the user groups that a user belongs to, you need to use this function in conjunction with the ds_UsersUserGroups function. The UserGroup item in the queue will contain the first user group that the user belongs to (making sure that your existing code will not break when upgrading to Secwin 4) - but the user may belong to more than one group, in which case it will be necessary to call the additional function as well.

Structure

ds_UserQueueEx       QUEUE,PRE(_dsqex)
Name                   STRING(40)
Surname                STRING(40)
Login                  STRING(128)
UserGroup              LONG
Number                 LONG
LastPasswordChangeDate LONG
Reserved1              LONG
Reserved2              STRING(12)
Reserved3              STRING(20)
                     end

Purpose

This function fills into a queue, all the users and user groups currently in the database. In other words by using this function you can get the logins and other details of all existing users and user groups.

Returns

Nothing. The queue you passed now contains all the user details.

Example

ds_UserQueueEx       QUEUE,PRE(_dsqex)
Name                   STRING(40)
Surname                STRING(40)
Login                  STRING(128)
UserGroup              LONG
Number                 LONG
LastPasswordChangeDate LONG
Reserved1              LONG
Reserved2              STRING(12)
Reserved3              STRING(20)
                     end

  code
  ds_Users (Appnum,ds_UserQueueEx)

See Also

ds_UpdateUser, ds_UsersUserGroups

ds_UpdateUsersUserGroups (long pAppNum,long pUser,string pUserSite,ds_UsersUserGroupsQType pUserGroupsQu,long pForce=0),long

Purpose

This function updates all the usergroups that this user belongs to from a previously populated UserGroup Queue (which you use ds_UsersUserGroups function to populate this queue with).

You can remove or add the user specified in the pUser field to any number of usergroups in the user group, as follows:

UsersUserGroups.ActiveIcon = 2  !Adds the user to the user group.

UsersUserGroups.ActiveIcon = 1  !Removes the user from the user group.

Similarly, if you have other users that must be associated with the usergroups of another user, you can retrieve the UserGroups using the ds_UsersUserGroups function (using the user id of the "from" user) and send the pUser to the user that you want to associate the same usergroups to.

Note: When adding/removing a user from a user group - leave the Active flag in the state it was in (when it was returned from the ds_UsersUserGroups function) - and only change the ActiveIcon flag. Secwin will comppare the flags to see where the changes have occured (rather than applying a change to every record that is in the queue - which is really inefficient).

Returns

Indicates whether a add to or remove from Usergroup failed:

0 - No error
1 - Removing the user from one or more usergroup(s) failed.
2 - Adding the user to one or more usergroup(s) failed.
3 - Adding to and removing from failed.

You can loop through the queue and see which records failed by testing (see example code for details).

Example code:

UsersUserGroups QUEUE(ds_UsersUserGroupsQType),PRE(SecLocUUGQ) !
                           END
UserNumber        long        !The ID of the user

  code
     UserNumber = ds_GetUserProperty(AppNum,Login,,'UserNumber')        !This gets the usernumber for the user
     if ds_UsersUserGroups(AppNum,UserNumber,'',UsersUserGroups,0) .         !Load the Users usergroups list
         !First retrieve the user group you are wanting to alter
     Get(UsersUserGroups,<UserGroupToGet>)
         !Code in here to toggle the group that the user belongs to as follows:
     if UsersUserGroups.ActiveIcon = 1
       UsersUserGroups.ActiveIcon = 2       !The user is part of the UserGroup
     else
      UsersUserGroups.ActiveIcon = 1       !The user is not part of a UserGroup
     end
     put(UsersUserGroups)
     if ds_UpdateUsersUserGroups(Appnum,UserNumber,'',UsersUserGroups)
       loop Counter = 1 to records(UsersUserGroups)
         get(UsersUserGroups,Counter)
         if ~errorcode() and UsersUserGroups.ActiveIcon <> UsersUserGroups.Active + 1
           !What to do if the changed didn't take
         end
       end
     end 

See also:

ds_UsersUserGroups , ds_GetUserProperty

ds_UsersUserGroups (long AppNum,long pUser,string pUserSite,ds_UsersUserGroupsQType pUGQueue,long pOptions=1,<*string pChangeAccess>,long pHash=0),long

Structure

ds_UserSUserGroups       QUEUE(ds_UsersUserGroupsQType ),pre(UUG) .   !You must have a prefix - otherwise you'll get compile warnings on this line

Purpose

This function populates a queue with all the user groups that a user belongs to. You can either use it to populate an exhaustive list of UserGroups and highlight the user group using the active flag (like with a style or Icon in a list) or only return a list of the user groups that the user belongs to (depending on the pOptions flag passed to the function). For example, if you have the following usergroups in this application:

StockControl
Accounts
Invoicing
OrderEntry
Receiving

And you would like to display all 5 with a checkbox next to the UserGroups that a particular user belongs to, then you would set the pOptions to 0 (or omit the parameter). The Active element of the queue will be set for those entries that the user belongs to. To just return the UserGroups that a user belongs to (without returning all of the possible UserGroups) - set the pOptions to 1.

Returns

Nothing. The queue you passed now contains all the usergroup details.

Example

      !This goes in your local data section
ds_UsersUserGroupsQ       QUEUE(ds_UsersUserGroupsQType),pre(UUG) .
MyUser                    long

  code
    ds_UsersUserGroups(AppNum,MyUser,'',ds_UsersUserGroupsQ) !The Queue will contain all UserGroups with the Active Flag set for the ones that the User belongs to.
    ds_UsersUserGroups(AppNum,MyUser,'',ds_UsersUserGroupsQ,1) !Contains just the UserGroups that the user belongs to

See Secwin Data Types for more details on the Queue structure.

See also: ds_LoginUser, ds_GetProperty . This function essentially replaces the obsolete ds_CurrentUserGroup function.

To change from using the ds_CurrentUserGroup function, you might have had something like:

if ds_CurrentUserGroup (Appnum)= 'MyUserGroup'
  !Some functionality in here
end

Now, you need to declare the Queue as shown above (in your local data), and replace the code with the following:

ds_UsersUserGroups(AppNum,MyUser,'',ds_UsersUserGroupsQ,1)
loop x# = 1 to records(ds_UsersUserGroupsQ)
  get(ds_UsersUserGroupsQ,x#)
  if UUG:GroupName = 'MyUserGroup'
    !Somefunctionality in here
    break
  end
end

ds_GetUserPassword(long pUser,string pUserSite),string

Purpose

This function returns the user's password (specified by the pUser parameter). This must be used in conjunction with the use of the ds_SetEncryptionKey (see Using an encryption key for details)

Returns

A string containing the user's password.

Example

UsersPassword            string(128)

  code
    UsersPassword = ds_GetUserPassword(MyUser,'')

See also: ds_SetEncryptionKey , ds_ResetUserPassword . To get the user number, use the ds_GetUserProperty function.

ds_ResetUserPassword(long pUser,string pUserSite),long

Purpose

This function resets the user's password (specified by the pUser parameter) to the default (i.e. their login). This must be used in conjunction with the use of the ds_SetEncryptionKey (see Using an encryption key for details)

Returns

A long indicating pass (0) or failure (non-zero).

Example

ReturnValue            long

  code
    ReturnValue            = ds_ResetUserPassword(MyUser,'')

See also: ds_SetEncryptionKey , ds_GetUserPassword  . To get the user number, use the ds_GetUserProperty function.

ds_SetEncryptionKey(string pEncryptionKey)

Purpose

This function sets the encryption key used to encrypt the necessary fields in the Secwin operators table (see Using an encryption key for details). Once this function has been used, and your application has been run on the Secwin data tables, then only your application will be able to read the secwin operators table.

Returns

Nothing.

Example

ReturnValue            long

  code
    ds_SetEncryptionKey('MyEncryptionKey')

See also: ds_ResetUserPassword , ds_GetUserPassword 

Secwin Data Types

The following data types are used by some of the functions and may be used in your application as well from time to time:

The complete data structures of these types may be found in the secequ15.clw file in your clarionx\3rdparty\libsrc directory.

Installation

Run the Supplied Installation file.

Distribution

You are free to distribute the Secwin DLLs with any of your Applications without extra charge.

You are free to distribute the CRESEC.EXE or any of the Example programs should you want to.

The DLLs your program require will depend on your version of Clarion and the Secwin File Driver you are using. Note that programs compiled in Local Mode do not use DLLs and therefore there is nothing extra for you to distribute.

	Clarion 6	Clarion 5.5	Clarion 7
Topspeed Driver	S6TPSX.DLL	S55TPSX.DLL	S70TPS.DLL
Btrieve Driver	S6BTRX.DLL	S55BTRX.DLL	S70BTR.DLL
SQL Anywhere Driver	S6SQAX.DLL	S55SQAX.DLL	S70SQA.DLL
MsSQL Driver	S6MSSX.DLL	S55MSSX.DLL	S70MSS.DLL
ODBC Driver	S6ODBCX.DLL	S55ODBCX.DLL	S70ODB.DLL
IPDriver	s6IPDx.DLL
Pervasive SQL Driver	s6SCAx.DLL	s55SCAx.DLL	s70SCA.DLL
Oracle Driver	s6ORAx.DLL	s55ORAx.DLL	s70ORA.DLL

License & Copyright