CAN-DO function

Checks a user ID against a list of one or more user ID matching patterns that can be used to indicate what users have access to a given application function. The function returns TRUE if the specified user ID has access according to the list. Thus, you can implement run-time authorization checking for any procedure or class in your application.

Syntax

CAN-DO ( id-pattern-list [ , userid ] )

id-pattern-list

A constant, field name, variable name, or expression that evaluates to a list of one or more user ID patterns. Each user ID pattern must be in the form of a table and field permission string that you might specify when editing data security with database administration tools. If the expression contains multiple user ID patterns, you must separate the patterns with commas. There can be no embedded spaces within or between the patterns in the list.

The following table lists some basic user ID patterns that you can include in id-pattern-list, where user-ID can be a fully qualified or non-qualified user ID, depending on your application and authentication design, and string is a sequence of characters from any user ID. For more information on fully qualified and non-qualified user ID's, see the reference entries for the QUALIFIED-USER-ID attribute, USER-ID attribute, and USERID function.

The patterns shown also support the use of a period (.) as a wildcard for a single character matches. For example, CAN-DO("a.c","abc") evaluates to TRUE.

Basic patterns to use in user ID pattern lists

Value	Meaning
*	All users have access.
user-ID	This user has access.
!user-ID	This user does not have access.
string*	Users whose IDs begin with string have access.
!string*	Users whose IDs begin with string do not have access.

You can use any combination of patterns to define id-pattern-list. These patterns are fully consistent with the permissions that you can define for OpenEdge database tables and fields using database administration tools.

The following table shows some examples of fully qualified user ID matches.

Fully qualified user ID matches

This pattern...	Matches...
	The blank user name in the blank domain
*	All user ID's
mark@acme.com	The "mark" user name in the "acme.com" domain
mark	The "mark" user name in the blank domain
mark*	All user names that begin with "mark" in the blank domain
*jones	All user names that end with "jones" in the blank domain
db*user	All user names that begin with "db" and end with "user" in the blank domain
@acme	The blank user name in the "acme" domain
*@acme	All user names in the "acme" domain
@	The blank user name in the blank domain
mark@*	The "mark" user name in any domain
*@*	Any user name in any domain
mark*@acme.*	Any user name that begins with "mark" in any domain that begins with "acme."
*@*.admins	Any user name in any domain that ends with ".admins"

Note: For a more complete description of the possible patterns and their meanings, see OpenEdge Getting Started: Identity Management and the Database Administration online help.

userid

A character expression that evaluates to a user ID value that can be returned from the QUALIFIED-USER-ID attribute, USER-ID attribute, or USERID function. The userid is checked against id-pattern-list. If you do not enter userid, the compiler inserts the USERID function by default, which is evaluated each time you run the procedure or class. If the compiler inserts the USERID function, the function does not reference a database name and therefore only works for an ABL session with one database connection. If you explicitly use the USERID function and have more than one database connected, be sure to include the database name with the function call, for example, USERID("sports2000").

Examples

The r-cando.p procedure is based on an activity permission table called permission. This permission table is not included in any of the installed sample databases. However, the records in this table contain two fields and might look something like the following:

In r-cando.p the FIND statement reads the record for the activity "custedit" in the permission table. The CAN-DO function compares the value of USERID (the user ID of the single session database connection) with the list of users in the Can-Run field of the custedit record. If the user ID is "manager" or "salesrep", the procedure continues executing. Otherwise, the procedure displays a message and control returns to the calling procedure.

r-cando.p

DO FOR permission:
  FIND permission WHERE Activity = "custedit".
  IF NOT CAN-DO(permission.Can-Run, USERID) THEN DO:
    MESSAGE "You are not authorized to run this procedure".
    RETURN.
  END.
END.

In this next example, the CAN-DO function compares the value of USERID against the list of user ID patterns passed as a constant string to the function. The values in the constant string include "manager" and any user IDs beginning with "acctg" except "acctg8". If there is no match between the two values, the procedure displays a message and then exits.

r-cando2.p

IF NOT CAN-DO("manager,!acctg8,acctg@*", USERID) THEN DO:
  MESSAGE "You are not authorized to run this procedure.".
  RETURN.
END.

Notes

• If id-pattern-list contains contradictory values, the first occurrence of a value in the list applies. For example, CAN-DO("abc,!abc*") evaluates to TRUE, because the user ID, "abc", appears before "!abc" in id-pattern-list.
• If id-pattern-list is exhausted without a match, CAN-DO returns a value of FALSE. Therefore, "!abc" restricts "abc" and everyone else, including the blank user ID (""). To restrict "abc" only and allow everyone else, use "!abc,*".
• A userid comparison against id-pattern-list is not case sensitive.
• If a user is logged into a UNIX system as root, the AVM allows access to the procedure even if access is denied by the id-pattern-list. You must specifically deny root access by adding "!root" to the id-pattern-list.
• In addition to the examples shown above, you can use the CAN-DO function to compare a userid other than that of the current user against the list of values in id-pattern-list. For example, to assign a department userid to users "smith" and "jones" when they start the ABL session, you can prompt these users for a department userid and password and check them against a table of department ID's.
• You can pass user IDs to the CAN-DO function, other than the default, that have been set using command-line database connections, the CONNECT statement, the SECURITY-POLICY:SET-CLIENT( ) method, the SET-DB-CLIENT function, or the SETUSERID function.
• You can use the CAN-DO function to match a user ID against run-time table and field permissions stored in an OpenEdge RDBMS by accessing the user ID patterns stored in the _Can-* fields of the _File metaschema table.
• ABL raises an error if you omit userid and one of the following conditions exists:
  • There is no database connected.
  • More than one database is currently connected.
• By default, CAN-DO treats "@" as a delimiter for the domain name in a fully qualified user ID. However, you can change this functionality so that CAN-DO treats "@" as a regular character by using the CAN-DO-DOMAIN-SUPPORT attribute of the SECURITY-POLICY handle or the -nocandodomain startup parameter. For more information on the -nocandodomain startup parameter, see the OpenEdge Deployment: Startup Command and Parameter Reference.

See also

CAN-DO-DOMAIN-SUPPORT attribute, CONNECT statement, QUALIFIED-USER-ID attribute, SET-CLIENT( ) method, SET-DB-CLIENT function, SETUSERID function, USERID function