$ROLES (ObjectScript)

Contains the roles assigned to the current process.

Synopsis

$ROLES

Description

$ROLES contains the list of roles assigned to the current process. This list of roles consists of a comma-separated string that can contain both Login Roles and Added Roles.

A role is assigned to a user either by using the SQL GRANT statement, or by using the Management Portal System Administration, Security, Users option. Select a user name to edit its definition, then select the Roles tab to assign that user to a role. A role can be defined using the SQL CREATE ROLE statement and deleted using the SQL DROP ROLE statement. A role must be defined before it can be assigned to a user. A role can be revoked from a user using the SQL REVOKE statement.

When a process is created using the JOB command, it inherits the same $ROLES and $USERNAME values as its parent process.

When a process performs I/O redirection, this redirection is performed using the user’s login $ROLES value, not the current $ROLES value.

SET $ROLES

You can use the SET command to change the Added Roles contained in $ROLES. Setting $ROLES does not alter a process’s Login Roles.

Setting $ROLES to a non-empty list is a restricted system capability, requiring READ and WRITE permissions on the %DB_IRISSYS resource. Attempting to modify $ROLES without the necessary privileges results in the <PROTECT> error. Alternatively, users without those permissions can call routines stored in the IRISSYS database that themselves modify $ROLES.

The above restrictions do not apply to setting $ROLES to a null string, which removes all Added Roles.

A role must be defined before it can be added. You can define a role using the SQL CREATE ROLE command. CREATE ROLE does not give any privileges to a role. To assign privileges to a role, use the SQL GRANT statement or the Management Portal System Administration, Security, Roles interface.

You must issue a NEW $ROLES statement before escalating the process roles using SET $ROLES.

NEW $ROLES

NEW $ROLES stacks the current values of both $ROLES and $USERNAME. You can use the NEW command on $ROLES without security restrictions.

Issue a NEW $ROLES and then SET $ROLES to supply Added Roles. You can then create an object instance that uses these Added Roles. If you quit this routine, InterSystems IRIS closes the object with the Added Roles before reverting to the stacked $ROLES value.

Examples

The following example returns the list of roles for the current process.

   WRITE $ROLES

The following example first creates the roles Vendor, Sales, and Contractor. It then displays the comma-separated list of default roles (which contain both Login Roles and Added Roles). The first SET $ROLES replaces the list of Added Roles with the two roles Sales and Contractor. The second SET $ROLES concatenates the Vendor role to the list of Added Roles. The final SET $ROLES sets the Added Roles list to the null string, removing all Added Roles. The Login Roles remain unchanged throughout:

CreateRoles
   &sql(CREATE ROLE Vendor)
   &sql(CREATE ROLE Sales)
   &sql(CREATE ROLE Contractor)
   IF SQLCODE=0 { 
     WRITE !,"Created new roles"
     DO SetRoles }
   ELSEIF SQLCODE=-118 {
     WRITE !,"Role already exists"
     DO SetRoles }
   ELSE { WRITE !,"CREATE ROLE failed, SQLCODE=",SQLCODE }
SetRoles()
     WRITE !,"Initial: ",$ROLES
     NEW $ROLES
     SET $ROLES="Sales,Contractor"
     WRITE !,"Replaced: ",$ROLES
     NEW $ROLES
     SET $ROLES=$ROLES_",Vendor"
     WRITE !,"Concatenated: ",$ROLES
     SET $ROLES=""
     WRITE !,"Nulled: ",$ROLES