Main Documentation

Secwin Technical Reference - obsolete and deprecated functions

ds_Allowed (ApplicationNumber , FunctionName, Override)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
FunctionName	String	This is the name of the function to which the user is requesting access. This parameter is not case sensitive.
Override	Long	This is an attribute that contains any overrides that the program may use to override the users access levels. This is not currently used and should be set to 0.

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

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
Login	String	Optional. A default value for the Login.
Password	String	Optional. A default value for the Password.
Options	Long	Optional. Explained below

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_LoginText. This function behaves the same as the ds_LoginText 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_LoginText, Code : Change Login, Making your own Secwin windows

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)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
OldPassword	String(12)	The users old password
NewPassword	String(12)	Contains the new password
VerifyPassword	String(12)	Contains a copy of the new password.
Options	Long	Described below

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_ChangeUser( AppNum, FirstName, LastName, LoginCode,  Workgroup, Level, UserGroup)

Parameter Name	Type	Description
AppNum	Long	The application number of the current application as returned by the ds_LoginText function.
FirstName	String	Obvious (for Users). If the UserGroup parameter is set to -1 then this contains the UserGroup Name.
LastName	String	Obvious (for Users). If the UserGroup parameter is set to -1 then this contains a space followed by the UserGroup Name.
LoginCode	String	The code the user will use when he logs in. His initial password will also be set to this value.
WorkGroup	Long	The users Workgroup number. this is the same as the Workgroup field on the usual operator form.
Level	Long	One of DS_SUPERVISOR, DS_OPERATOR or DS_NOACCESS
UserGroup	Long	User Group Number. If this is set to -1 then this is a UserGroup (not a User) being added.

Lets you change a user (or user group) in source code.

Returns

0 if successful. 
1 if the operator doesn't exist. 
2 if some file-access-error prevented the delete. Use ERRORCODE() to get the actual error.

Example

  code
  execute ds_ChangeUser(App,FirstName,LastName, LoginCode,WorkGroup, Level,0)
    message('Operator Not Found')
    message('Error Writing Record: ' & Error())
  end

See Also

ds_InsertUserEx, ds_DeleteUser

ds_CountUsers( SecurityAreaName)

Parameter Name	Type	Description
SecurityAreaName	String	This is the name of the area being protected. Each name must be unique, even across applications, so by convention, this name is normally made up of the application name and the area name, separated by a pipe ( | ) symbol. The maximum length of this parameter is 43 characters, and it is not case sensitive. This is the same as the SecurityAreaName parameter from the ds_LoginText function.

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_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_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_CurrentLastPasswordChange (ApplicationNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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_CurrentOperatorNumber (ApplicationNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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_CurrentLogin (ApplicationNumber )

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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 )

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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_CurrentUserGroup (ApplicationNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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

ds_CurrentWorkGroup (ApplicationNumber )

Obsolete. Use ds_CurrentWorkGroupEx instead.  ds_CurrentWorkGroup returns a Short not a Long.

ds_CurrentWorkGroupEx (ApplicationNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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_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_DeleteUser (ApplicationNumber , Login)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
Login	String	The login code of the operator being deleted.

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_GetAccessEx (ApplicationNumber, CalledBy, User )

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
CalledBy	String	This is a unique string for this procedure. Usually the procedure name.
OperatorNumber	Long	This is the number for the current Operator as returned by ds_CurrentOperatorNumber  or in the users Queue returned by ds_UsersEx.

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

Parameter Name	Type	Description
Product	String	The name of your product as specified in the Secwin Global Extension.
Company	String	The name of the company which has bought the software.
SerialNumber	String	The serial number you have issued the company mentioned above.
Copies	Long	The number of concurrent network copies they are allowed to run.
Level	Long	The level they have purchased. 1 = Demo, 2 = Lite etc. ( Valid 1- 5 )
Optional	Long	A bit mask of the optional modules they have purchased. 1 is module 1, 2 is module 2, 4 is module 3, 8 is module 4 etc. So to activate modules 2 and 4 this would be set to 10 ( 2+8 ).
ExpiryDate	Long	The date when the user's license will expire. This is a standard clarion date.
Counter	Long	The counter field.
SeedCode	Long	The seed code of the application as specified on the Secwin Global Extension.

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_GetWorkGroup (ApplicationNumber, OperatorNumber)

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

ds_GetWorkGroupEx (ApplicationNumber, OperatorNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
OperatorNumber	Long	This is the number for the current Operator as returned by ds_CurrentOperatorNumber  or in the users Queue returned by ds_UsersEx.

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)

Parameter Name	Type	Description
SecurityAreaName	String	This is the name of the area being protected. Each name must be unique, even across applications, so by convention, this name is normally made up of the application name and the area name, separated by a pipe ( | ) symbol. The maximum length of this parameter is 43 characters, and it is not case sensitive. This is the same as the SecurityAreaName parameter from the ds_LoginText function.
FirstName	String	Firstname of the user being added. Ignored if Number <> 0.
LastName	String	Lastname of the user being added. Ignored if Number <> 0
LoginCode	String	The code the user will use when he logs in. His initial password will also be set to this value. Ignored if Number <> 0.
Number	Long	The User Number of an existing User to be granted First User rights to this area. If 0 then a new user (using the above parameters) will be created.

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

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

Parameter Name	Type	Description
AppNum	Long	The application number of the current application as returned by the ds_LoginText function.
FirstName	String	Obvious (for Users). If the UserGroup parameter is set to -1 then this contains the UserGroup Name.
LastName	String	Obvious (for Users). If the UserGroup parameter is set to -1 then this contains a space followed by the UserGroup Name.
LoginCode	String	The code the user will use when he logs in. His initial password will also be set to this value.
InitialAccess	Long	1 = All Access otherwise No Access.
WorkGroup	Long	The users Workgroup number. this is the same as the Workgroup field on the usual operator form.
Level	Long	One of DS_SUPERVISOR, DS_OPERATOR or DS_NOACCESS
UserGroup	Long	User Group Number. If this is set to -1 then this is a UserGroup (not a User) being added.

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_LoginText (SecurityAreaName, Options, Login, Password)

Parameter Name	Type	Description
SecurityAreaName	String	This is the name of the area being protected. Each name must be unique, even across applications, so by convention, this name is normally made up of the application name and the area name, separated by a pipe ( | ) symbol. The maximum length of this parameter is 43 characters, and it is not case sensitive.
Options	Long	This parameter governs the behaviour of the Login function. Multiple options can be added together. Possible values are listed below.
Login	String	This is the default Login code. In order for this to be used by this function, the DS_AUTOLOGON option flag must be set. Can be blank.
Password	String	This is the default Password. In order for this to be used by this function, the DS_AUTOLOGON option flag must be set.

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_OPTIONALON : This indicates that this login is optional, and is governed by your user at runtime. If any user has been given access to this area, then a login is required. If no user has been assigned access then no login screen is presented. When inside an optional area all users have supervisor status i.e. no Screen Security is in place. A user can change the optional status of the area by entering the area, then opening the Browse Users screen. They can then assign a supervisor to the area, and from then on the area is not optional, until all users have been assigned 'No Access' again.

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.

DS_AUTOLOGON : Allows this application to accept automatic login attempts, using the Login and Password parameters.

DS_DONTSHOWSCREEN : If this flag is set, and the DS_AUTOLOGON flag is set, and the attempted automatic login fails, then the function will immediately return 0, without opening the login screen. If this flag is not set, and an automatic login attempt fails, then the normal login screen will be opened.

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.

If the DS_AUTOLOGON flag is set then the function will attempt to log the user in using the Login and Password parameters.

If either of these attempts fail, then the normal login screen will be displayed. If the DS_DONTSHOWSCREEN option flag is set then the function won't open the screen, but will return 0.

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_LoginText automatically logs out the existing user for this instance of the area, if one exists. In other words calling ds_LoginText (SecurityAreaName, x) causes an implicit ds_Logout (ApplicationNumber) - i.e. a logout of the same area - to be called before ds_LoginText. If no user is logged in then ds_Logout ignores the request.

Example, for applications with one login area

AppNum long

  Code
  AppNum = ds_LoginText ('Video.Exe', DS_OPTIONALON +DS_CASESENSITIVITYOFF,'','')
  if AppNum = 0
    ! login was unsuccessful
    return
  End

Example, for applications with multiple login areas

AppNumQueue Queue
AppNum long

  code
  AppNum = ds_LoginText ('Video.Exe', DS_DEFAULT,'','')
  if AppNum = 0
  ! login was unsuccessful
    return
  End
  Add(AppNumQueue,1)
  !< Function code goes here >
  ds_Logout (AppNum)
  delete (AppNumQueue)
  get (AppNumQueue,1)
  return

See Also

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

ds_Logout (ApplicationNumber)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.

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 reenter 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_LoginText ('Video.Exe', ds_DEFAULT,'','')
  if AppNum = 1
    ! login was unsuccessful
    return
  End

  < function code goes here >

  result = ds_LogOut (AppNum)
  return

See Also

ds_LoginText

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

Parameter Name	Type	Description
Product	String	The name of the product.
Seed	Long	The developer's seed code.
Options	Long	Various options, described below.
Company	String	The name of the company the product is licensed to.
SerialNumber	String	The serial number of the product.
Copies	Long	The number of copies that the user may simultaneously run on a network.
Level	Long	The level that the user is licensed to.
Modules	Long	The optional modules that the user has access to.
Activation Code	String	The activation code as returned by ds_GenerateActivationCode.
Counter	Long	The number that the Counter must be set to.

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

NOTE: This function relies on the existence 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_SecwinMakeover (MakeoverObject)

Parameter Name	Type	Description
MakeoverObject	Makeover	A reference to a Makeover objected created in the Exe. This would typically be ThisMakeover

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

CapeSoft Makeover Compatability

ds_SetAccess (ApplicationNumber ,ScreenName, Options)

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
ScreenName	String	This is the name of the screen or function. This name must be unique within an application.
Options	String	This string contains all the access options for this function. Each item in the string is separated by a pipe (|) character. There may be up to 8 items in the string. Each item must be 6, or fewer, characters long. These items then appear on the Set Access screen in different columns.

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 )

Parameter Name	Type	Description
ApplicationNumber	Long	This is the Application number returned by ds_LoginText.
CalledBy	String	This is a unique string for this procedure. Usually the procedure name.
OperatorNumber	Long	This is the number for the current Operator as returned by ds_CurrentOperatorNumber  or in the users Queue returned by ds_UsersEx.
Rights	Long	These is the rights for this operator, for this window. Each bit represents a different right. This is matched to the number

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_UseLicence (ProductName, ApplicationNumber, LicenseName, Options)

Parameter Name	Type	Description
ProductName	String	This is the name of the product. This name is used when generating activation codes.
ApplicationNumber	Long	This is the Application number returned by ds_LoginText. If you are not using a login then set this number to 0.
LicenseName	String	This is a unique, 4 character, string containing the unique license name for this product. You may use alphanumeric characters only. It is case insensitive.
Options	Long	A long number containing a number of different bit settings. This variable can contain either (or both) of the following options; DS_NODEMO DS_NONETWORKCHECK The 3rd byte in the long (ie options/65536) contains the length of the demo license. The default is 30 days.

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_LoginText 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_LoginText 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_LoginText('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_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.

Parameter Name	Type	Description
UserQueue	ds_UserQueueType	This is a queue defined in your application using the ds_UserQueueType queue structure. the queue you pass must have this structure. An example of such a queue is

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

Global Extension : Activate Secwin features

Visible Effect to your App

None

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

Application Tab	Unique Application Name	Enter a unique name for this Application.
	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 is Secwin is the source of your problem.
Licensing Tab	License Name	This is the name of the license for this application. when generating activation codes this corresponds to the Application Name.
	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.
Multi-DLL Tab	This is Part of a Multi-DLL Application	If this APP is part of a Multi-DLL application then click this on.
	Secwin Data Defined in another DLL	Click this on if this is NOT the data DLL.
	Don't Generate AppNameDesc	If you are using Multi-Proj then the Global data from the Data DLL will automatically be included here. If so click this on. Otherwise Secwin will need to generate the data here, in which case click this off.
	Export Secwin data defined in this DLL	If this is the Data DLL then tick this option on.
Files Tab	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. Will only show installed driver packs. 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 optional. 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 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 Path	Set the default position of the Language File.
Advanced Tab	Font	Set the Font which you want the Secwin screens to use.
	Application Pin	See Application Pin Numbers in the User Guide.
	SetAccess Function Override	Use thisif you've created your own SetAccess function. See Making your own Secwin Windows.
	I'm using 9046	Check this if you are using Clarion 6.2 9046. This will force the inclusion of the secequ60.clw file (not required in 9047 and up, but required in Clarion 6.1 and down).

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

Options

Do not Call ds_GetCurrent	Click on this if you do not want the Logo Screen to automatically load the current license details.
Level Names	If you want to change the names of the different levels then enter them here.

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 on Extensions
4. Click on Add
5. Choose RunLogoScreen Extension

Options

Logo Procedure

This is the name of the Logo Procedure to use. The Logo procedure should use the MakeLogo Extension.

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 the Properties button.
4. Click on Extensions
5. Click on Add
6. Choose User Login Here from the list of available extensions

Options

Login Options Tab	Unique Area Name	This is the name for this login area. A program can have multiple login areas (each one with a unique name). If you have only one login area (as is probably the case) then you can just use the word Main.
	Allow Case Insensitive Password	If this is ticked then passwords will be case insensitive. If this is off, then passwords will be case sensitive.
	Make Login Optional to End User	If this option is ticked, and there are NO users defined then the login screen will not be displayed. If this option is not ticked, and no users exist, then the user will be prompted to add the first user.
	Allow only 3 tries	If this is ticked, and the login fails 3 times, then the program will close.
	Allow Automatic Login from other EXEs	If this option is ticked on then you'll be able to automatically log into this program from other Secwin enabled programs, using the ds_Run template, or function.
	Allow Default Login values	If this is on, then you can set default login and password values. This allows you to 'auto-login' as well as supporting your own Login window.
	Default Login Code	Set this to a fixed value in 'quotes' - or a variable name.
	Default Password	Set this to a fixed value in 'quotes' - or a variable name.
	Don't show screen if default fails	If the default login fails, and this is ticked on, then the Secwin Login window will not be displayed. Otherwise the Secwin Login window will be displayed with the primed values.
	Force Password change every 30 days	If this is on the user will be asked to change their password every 30 days.
	Force Long password	If this is on then the user will be forced to have a password containing at least 6 alpha characters and 3 numeric characters.
	Use Own Login Screen	If this is on then you can use your own Login screen instead of using the Secwin one.
	Login Procedure	If the previous option is on then enter the Procedure name here.
	First User Procedure	If the Make Login Optional item is off, and Use Own Login Screen is on, then you should also create your own FirstUser procedure. Enter the name of this procedure here. If you leave this blank then everything still works, but it won't be ClarioNet compatible, and the sequence of events during the first login will appear a bit wierd.
	Display Login After Window Displays	If this is on, then your Frame will display before the login window. Normally the login window displays before the Frame window.
Licensing Tab	Activate Licensing Support	Click this on to activate the licensing for this login. Typically you'll click this on for a single login in your application, usually the one on the frame. (Remember you app could have multiple login screens.)
	Default to demo license	If you ship a security file with No license, and this option is on, then the user will automatically get a demo level license the first time the program is run. Note they will ONLY get 1 demo license. Deleting the dssw4 file will NOT result in another license.
	Valid for (days)	Active if the Default to Demo License is on. Default is 30 days. Set the length of time (in days) that you want the demo to last for.
	Level	Allows you to set what Level will be set when the Demo License is made. In the past this had to be Level Demo, now you can choose
	Allow Multiple Security Files	By default Secwin monitors the dssw4 file. If the user has 2 dssw4 files, or restores a backup, then Secwin will complain with a "Security File Corrupted" message. Click this option on override this check.
	Disable Network Licensing	If this option is ticked on then the Concurrent Network Copies feature will not be enforced.
	Unique License Code	Enter a 4 character (no spaces) code here. This, along with a 4 digit number, will be used to name the .LIC files used for network copies.
Super User Tab	Enable Super User	Tick this option on to enable Super Users.
	Super User Login Code	Enter the Super User's Login code here. Note Super Users are probably not what you think they are See the section in the User Guide for more information.

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 the Properties button.
4. Click on Extensions
5. Click on Add
6. Choose User Screen Security from the list of available extensions

Options

General Tab	This Procedure Doesn't have a window	This is used when you are adding licensing support to a procedure which doesn't have a window - like a report.
	Control Restrictions Button	Contains all the restrictions for the Access Control features. See below for more information.
	License Check and Restrictions Button	Contains all the restrictions for the Licensing features. See below for more information.
	Disable Screen Security Here	Click on this option to disable all the Secwin Screen Security in this procedure. In other words this is like deleting the extension, except that all your current settings are kept. This is useful if you suspect that this extension is causing a problem in your window.
Control Restrictions Button	Unique Bit Position	You are allowed up to 30 groups of controls per window. Each group (a group may be just 1 control) needs a unique, unchanging number, from 1 to 30. Enter that number here.
	Name	Enter the name of the group here. This name will be used on the Set Access window.
	Use Equate	Enter the equate label for the first control in the group here. (Most groups will probably have just this primary control). You can select the control from the drop down list box.
	Column	If the control set in the previous setting is a list box, then you can protect just a single column of the list box if you like. (If you leave this as 0 then the whole list box will be protected.). Enter a column number in here if you want to protect just a single column.
	Action	This determines what happens if the user does not have access to the control. For buttons and menu items Disable is recommended, for entry controls you probably want to Hide the controls. Occasionally (mostly with text-boxes) it's useful to set the control to Read-Only. This allows the user to cut & paste the entry, but not change it. This is useful for address fields and things like that.
	Attach other Controls	I mentioned above that you can apply the settings to a group of controls. By clicking on this button you can add more controls to the group
License Restrictions Button	Disable all License checking here	Click this on if you want to bypass all the license checks here. Typically you'd do this if the extension has been added for the Access security above, but you want to prevent license checks.
	Disable Valid License File Check here
	Disable Valid Date Check here
Expiry Tab NEW	Warn of Impending Expiry	Click this on if you want Secwin to automatically warn the user when their program is nearing an expiry date.
	Warning Period	This sets the length of the warning period in days. For example, if set to 14, then the program will start warning the customer 14 days before it expires.
	Action : Display Message	This allows you to specify the text of the message that will be displayed.
	Action : Call Procedure	This allows you to specify a procedure that mst be called. You can then create your own window procedure to display whatever you like.
Levels Tab	Level Required for this screen.	If you set this to say Standard, and the user only has level Demo, or Lite, then this will cause the License to fail.
NEW	Control Restrictions	This allows you to restrict access to individual controls based on the Level. You can add as many controls as you like, and you can set the option to either hide, or disable, the control if the license fails.
Modules Tab	Optional modules required for this screen.	If you set any of the options on here, then the user will require the same module to be set, or the license will fail. For example if this procedure belongs to your General Ledger module (module 1) then you would click on optional module 1 here. If the user doesn't have the General Ledger then the license will fail.
NEW	Control Restrictions	This allows you to restrict access to individual controls based on the Optional Modules that are activated. You can add as many controls as you like, and you can set the option to either hide, or disable, the control if the license fails.
Action Tab	Action to take if License fails	If the user doesn't have the correct level, or the correct optional modules, or the license has expired, or the license is invalid, or the user has run out of network copies, then the license will fail. Exactly what happens when the license fails is up to you.
		Show Warning and return to caller : This is the most common action. The user will see an error message and the procedure will close.
		Return to caller without showing warning : Use this if you're going to show your own warning.
		Disable all controls except.... : This option allows the window to continue opening, but all of the controls will be disabled (except for the ones you specify). This is useful on a frame so that the user can still run certain items (like Help | About) but not get into the bulk of the program.
		Call Procedure : If you have your own Product Registration window, then you might want to call it directly (especially if the license on the Frame failed).
Counter Tab	Decrement Counter Here	If you click this option on then the counter will be decremented when this procedure runs. If the counter is already at 0 then the license will fail. Use this feature when you want to limit your program by number of runs, or number of reports etc.

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. Choose Embeds
3. Choose After Opening Window
4. Choose the Call_Current code template

Options

Position in Status Bar	Enter the position in the status bar here.
Text	Enter any text here you want to appear before the variable part. For example if you're displaying the user's name then enter 'User Name' here. Use quotes for literal text, or a variable (without any !)
Call	Select the variable you want to display. Use Name for the user's name, Login for their Login code, or Level for their level

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

Put the result in

Enter a field which will contain the result. The field should be a Long.

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

Put the result in

Enter a Long field to contain the date.

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 on Embeds 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 the Call_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_CurrentlyLoggedIn 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_CurrentlyLoggedIn code template.
6. Close the windows in the normal fashion.

Code : Calling Change Login

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. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_ChangeLogin code template.
6. Close the windows in the normal fashion.

Options

1. This is CALLING the Secwin Change Login window	Click this option if you want the menu item to call Secwin's built-in Change Login window. OR
2. This is calling Your Own Change Login window.	Click this if you want the menu item to call your own Change Login window. OR
3. This IS the Ok button on your Change Login window.	Use this if this is the OK button attached to Your Change Login window.
Login	Enter a field name here which contains the Login code that the user just entered. (Only used if Option 3 above is chosen)
Password	Enter a field name here which contains the Password code that the user just entered. (Only used if Option 3 above is chosen)
Your Procedure	If you chose Option 2 above, then enter the name of your Change Login procedure here.
Parameters	If you chose option 2 above, then you can optionally enter your parameters to your procedure here. This is included for your convenience if you decide to make a procedure that accepts parameters.

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. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_ChangePassword code template.
6. Close the windows in the normal fashion.

Options

This is your own Change Password Window	If you've added this template to your own Change Password window, to the Ok button, then click this option on here.
Old Password	Enter a field name here which contains the Old Password that the user just entered.
New Password	Enter a field name here which contains the New Password that the user just entered.
Verify Password	Enter a field name here which contains the second copy of the new password that the user just entered.
Suppress Warnings	If this option is on then Secwin will not display any warnings if the request failed. This is usually done when you want to display your own warnings. See the ds_ChangePasswordEx docs for information on the possible error codes.

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

Company	Enter the company field here. This should be a String(40).
Serial Number	Enter the serial number field here. This should be a String(20).
Copies	Enter the copies field here. This should be a Long.
Counter	Enter the counter field here. This should be a Long.
Level	Enter the level field here. This should be a Byte.
Expiry Date	Enter the expiry date field here. This should be a Long.
Optional Modules	Enter the optional modules field here. This should be an Array of bytes. The array should have at least 30 items. If you select the name from the lookup, then Clarion will automatically populate the field with a subscript. e.g. Modules[1]. You should remove the subscript part. e.g. Modules.

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. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_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 on Actions for the control.
3. Choose Embeds
4. Choose Control Event Handling , after generated code, Accepted.
5. Choose the Call_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

General Tab	This is your own Register screen	Click this option on if you're using this embed on the Ok button of your own Product Registration screen. Click this option off if you are calling the default Product Registration window. The rest of the options you see will depend on this option.
Levels Tab	Allow the following Levels	Allows you to control what Levels appear on the default Secwin window. Select the Levels you want Secwin to offer.
Optional Modules Tab	Allow the following optional modules	Allows you to control which Optional Modules appear on the default Secwin Window. Select the modules you want Secwin to offer.
Fields Tab	Company	This is set if this is your own Register Product screen. Set the field to match the Company field that the user just typed in.
	Serial Number	This is set if this is your own Register Product screen. Set the field to match the Serial Number field that the user just typed in, or that you've set in your code.
	Copies	This is set if this is your own Register Product screen. Set the field to match the Copies field that the user just typed in, or that you've set in your code.
	Counter	This is set if this is your own Register Product screen. Set the field to match the Counter field that the user just typed in, or that you've set in your code.
	Level	This is set if this is your own Register Product screen. Set the field to match the Level field that the user just typed in, or that you've set in your code.
	Optional Modules	This is set if this is your own Register Product screen. Set the field to match the Optional Modules field that the user just typed in, or that you've set in your code.
	Activation Code	This is set if this is your own Register Product screen. Set the field to match the Serial Number field that the user just typed in.
Advanced	Counter is Relative	The counter setting will be added to the existing counter value.
	Activation code used once.	Prevents the same activation code being entered multiple times. Use when issuing relative counters to prevent multiple entry.

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

Program Name	Enter the program name to run here. This name can include the path if necessary.
Parameters	Enter any command line parameters, which will be sent to the new program, here.

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

Language File Name

Enter the name of the language file here. Use 'Quotes' if this is a fixed name, or enter a variable if you want the name of the file to be stored in a variable.

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\examplrs\secwin\setpin directory and the \clarion5\3rdparty\examples\secwin\hardpin 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. Choose Embeds
5. Choose Control Event Handling , after generated code, Accepted.
6. Choose the Call_SetPin code template.

Options

Application Name	Enter the name of the application here. You can use a variable, or 'quotes' for a fixed value.
Application PIN number	Enter the application Pin number in here.

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