Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).


Contains the roles assigned to the current process.




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

Roles Granted to Roles Not Listed

Granting a role to another role is a concept only available through Caché SQL. Roles granted to roles are used in SQL to determine the user's role list for checking SQL privileges. They cannot be accessed by ObjectScript. You cannot grant a role to another role through Caché System Security. Therefore, the $ROLES special variable list does not contain any roles that SQL operations have granted to the current roles. For further details, refer to the GRANT command in the Caché SQL Reference.


You can use the SET command to change the Added Roles part of the list contained in $ROLES. Setting $ROLES only alters a process' Added Roles. It cannot alter its User Roles. To set $ROLES to a different list of Added Roles is a restricted system capability. However, such restrictions do not apply to setting $ROLES to a null string, which deletes the list of 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 either 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 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, Caché closes the object with the Added Roles before reverting to the stacked $ROLES value.


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


The following example first creates the roles Vendor, Sales, and Contractor. It then displays the comma-separated list of default roles (which contain both User 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 User Roles remain unchanged throughout:

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

See Also