Advantage Client Engine
Grants to a user or a user group one or more permissions to a database object.
UNSIGNED32 AdsDDGrantPermission( ADSHANDLE hAdminConn,
UNSIGNED16 usObjectType,
UNSIGNED8 *pucObjectName,
UNSIGNED8 *pucParentName,
UNSIGNED8 *pucGrantee,
UNSIGNED32 ulPermissions );
hAdminConn (I) |
Handle of a database connection. |
usObjectType (I) |
Type of the database object that is specified by the pucObjectName parameter. Valid values are ADS_DD_TABLE_OBJECT, ADS_DD_COLUMN_OBJECT, ADS_DD_VIEW_OBJECT, ADS_DD_PROCEDURE_OBJECT or ADS_DD_LINK_OBJECT. |
pucObjectName (I) |
Name of the database object to grant the specified permissions on. It may be the name of a database table, the name of a column in a database table, the name of a view, the name of a stored procedure, name of a publication, name of a subscription, or a link alias. This parameter must be NULL or an empty string when granting CREATE permissions. |
pucParentName (I) |
Name of the database object that is the parent or owner of the object specified by pucObjectName. If usObjectType is ADS_DD_COLUMN_OBJECT, this parameter specifies the name of the database table that owns the column specified by the pucObjectName parameter. For other object types, the parameter can be NULL and it is ignored. This parameter must be NULL or an empty string when granting CREATE permissions. |
pucGrantee (I) |
Name of a user or a user group that is going to be granted the permissions. |
ulPermissions (I) |
This is a bit field specifying the access permissions to be granted to the user or the user group specified by the pucGrantee parameter. The permissions can be OR’ed together. Valid permissions are ADS_PERMISSION_READ, ADS_PERMISSION_UPDATE, ADS_PERMISSION_INSERT, ADS_PERMISSION_DELETE, ADS_PERMISSION_EXECUTE, ADS_PERMISSION_LINK_ACCESS, ADS_PERMISSION_INHERIT, ADS_ PERMISSION_ALTER, ADS_PERMISSION_DROP, ADS_ PERMISSION_CREATE, ADS_PERMISSION_WITH_GRANT, ADS_PERMISSION_ALL, and ADS_PERMISSION_ALL_WITH_GRANT. See Remarks for explanation on the effects of permissions. |
AE_INVALID_OBJECT_NAME |
The name specified by the pucObjectName, pucParentName or pucGrantee could not be found in the database. |
AE_INVALID_OBJECT_PERMISSION |
The permissions specified by the ulPermissions parameter contains a permission that is not valid for the specified object type or grantee type. |
AE_PERMISSION_DENIED |
The current user does not have permission to grant the specified permissions. |
AdsDDGrantPermission grants the specified access permissions to a user or a user group on a database object. The newly granted permission will be in addition to any existing permissions the user or the user group has on the specified database object. Permissions granted to views are not effected by the user’s permissions on the base tables used to construct the view. This behavior allows the use of views to control access to specific columns in the base tables. The following are valid permissions and a description of their effects on a user’s access to an object.
Note An older version dictionary may be upgraded to the latest version if necessary. This may be required to support new data dictionary functionality. See the Effects of Upgrading section in the current readme.txt file for any changes in behavior this may cause.
Note This function can be called inside a transaction, but will not be part of the transaction. Any changes it makes cannot be rolled back.
Note The ADS_PERMISSION_ALL permission equates to all the permissions for which the current user has ADS_PERMISSION_WITH_GRANT permissions.
usPropertyID |
Description |
ADS_PERMISSION_READ |
This permission can be granted to a user or a user group on a table, a view or a column object. A user must have read permission to a table or view to open the table directly or issue an SQL SELECT statement against the table. When the read permission is granted on a table, the read permission is implicitly granted to all columns in the table. When the read permission is granted to a column in a table, a partial read permission is granted for the table. If the user does not have full read permission to a table, the allowed access to the table is controlled by the table’s permission level property. See AdsDDSetTableProperty and ADS_DD_TABLE_PERMISSION_LEVEL for more information. |
ADS_PERMISSION_UPDATE |
This permission can be granted to a user or a user group on a table, a view or a column object. To modify existing data a user must be granted this permission. When this permission is granted on a table object, the permission is implicitly granted to all columns in the table. This permission affects SQL UPDATE statements and tables opened directly. |
ADS_PERMISSION_INSERT |
This permission can be granted to a user or a user group on a table, a view or a column object. A user must have insert permission to a table to insert new rows or provide data for a new row. Insert permission on a table or view allows the user to insert new rows into the table. Insert permission on column allows the user to provide data for a newly inserted row. If a new row is inserted into a table and the user does not have insert permission to some of the columns in the table, only default value can be posted to those columns. When granted to a table, this permission is implicitly granted to all columns in the table. This permission affects SQL INSERT statements and tables opened directly. |
ADS_PERMISSION_DELETE |
This permission can be granted to a user or a user group on a table or view object. This permission specifies whether the user can delete rows from a table or view. This permission affects SQL DELETE statements and tables opened directly. |
ADS_PERMISSION_EXECUTE |
This permission can be granted to a user or a user group on a stored procedure object. This permission affects SQL EXECUTE PROCEDURE statements. |
ADS_PERMISSION_LINK_ACCESS |
This permission can be granted to a user or a user group on a link object. If this permission is not granted, the user cannot access tables on the link. A link is a reference to another database managed by the Advantage Database Server or Advantage Local Server. See AdsDDCreateLink for addition information on links. |
ADS_PERMISSION_INHERIT |
This permission can be granted to a user on a table, a view, a stored procedure, subscription, publication, or a link object. With this permission, the user’s effective access permission to a database object is the sum of all permissions granted to the user and all user groups to which the user belongs. This permission can only be granted or revoked by the ADSSYS or members of the DB:Admin group and it cannot be granted with the ADS_PERMISSION_WITH_GRANT option. For columns in a table, the user inherits permissions from its user groups only when the user is granted inherit permission on the table. By default all users are granted the inherit permission to database objects. For example, if "Group1" has read permission to "table1" and read and update permission to "table2"; and "Group2" has update permission to "table1", after making "user1" a member of both "Group1" and "Group2", the effective permissions of the user are read and update for both "table1" and "table2". To restrict "user1" to read permission to "table1", the administrator can grant the user the read permission to "table1" and revoke the users inherit permission to "table1". See AdsDDRevokePermission for additional information. |
ADS_PERMISSION_ALTER |
This permission can be granted to a user or a user group on a table, view, user, user group, relation, procedure, link, subscription, publication, or the database itself. With this permission, the grantee can modify the privileged properties of the specified object. To grant ALTER permissions for the database object, simply set pucObjectName to "Database" and pucParent to NULL or an empy string. |
ADS_PERMISSION_DROP |
This permission can be granted to a user or a user group on a table, view, user, user group, relation, procedure, subscription, publication, or link. With this permission the grantee can remove (drop) the specified object from the database. |
ADS_PERMISSION_CREATE |
This permission can be granted to a user or a user group on a table, user, user group, view, procedure, subscription, publication, or link. With this permission the grantee can create new objects of the specified type as well as add existing objects to the database such as tables and indexes. To grant this permission simply set usObjectType to the desired database object type and set pucObjectName and pucParentName to NULL or empty strings. ADS_PERMISSION_CREATE cannot be OR’ed together with any other permission except ADS_PERMISSION_WITH_GRANT. |
ADS_PERMISSION_WITH_GRANT |
This permission allows the grantee to grant the specified permission to another user or user group. This permission cannot be used alone. It must be OR’ed together with the permission or permissions to be granted. If the grantee does not already have the specified permissions OR’ed with WITH GRANT, they will be granted the specified permissions. |
ADS_PERMISSION_ALL |
This permission grants all available permissions to the user or user group that are aplicable for the specified object. Note: The ADS_PERMISSION_ALL permission equates to all the permissions for which the current user has ADS_PERMISSION_WITH_GRANT permissions. |
ADS_PERMISSION_ALL_WITH_GRANT |
This permission is the same as ADS_PERMISSION_ALL except that it also gives the grantee WITH GRANT permissions for the specified object. |
ADS_DD_PUBLICATION_OBJECT |
Retrieves the name of a publication object. The pucParentName is currently ignored and assumed to be the database. |
ADS_DD_SUBSCRIPTION_OBJECT |
Retrieves the name of a subscription object. The pucParentName is currently ignored and assumed to be the database. |
The ulPermissions parameter is used to specify a combination of permissions to grant to the user or the user group. Assuming that the user currently has no permission (the inherit permission has been revoked) to an object, the following are some sample permissions combination and their effect on the user’s access to the object:
After granting this combination of permissions on a database table or view to a user, the user has full access to the table. The inherit permission is superfluous at this point because there is no addition permissions for the user to inherit. However, it is still meaningful because there may be other permissions in the future or the user may have certain permissions revoked on the table. This combination is not valid for column objects because of the inherit and delete permissions. This combination cannot be granted to a user group because of the inherit permission.
This combination can be granted to a user on a table or a view. Besides having read permission to the table or view, the user will inherit other permissions from the user groups that the user belongs to. Other possible permissions that the user could inherit are insert, update, and delete.
This permission can be granted to a user or user group on a table, a view, or a column object. If granted this permission, the user has read-only access to the object. If the object is a table, the effective rights for the user to the table are read only access to all columns because the inherit permission was not granted. The user’s permission to the table is independent of the permissions granted to the user groups that the user may be a member of. If this permission is granted to a user group, all users in the user group will have effective read permission to the table or the view, provided that the users have been granted the inherit permission.
This permission can be granted to a user on a table, a view or a stored procedure object. If granted this permission, the user can inherit permissions from the user groups they belong to. If the user is not a member of any user groups, the user will have no access to the object. If the user belongs to any user groups, the effective permissions for the user on the object is the sum of the permissions of all user groups that the user belongs to.
This combination can be granted to a user or user group on a stored procedure object. The user must be granted this permission to execute a stored procedure. If this permission is granted to a user group, all members of the user group who have been granted the inherited permission for the stored procedure can execute the stored procedure.
Note If the database is not set up to verify the user access permissions, the user’s access permissions will not be checked by the Advantage servers. See AdsDDSetDatabaseProperty and ADS_DD_VERIFY_ACCESS_RIGHTS property for more information. The property defaults to False on newly created data dictionary, effectively giving all users full access to all objects in the database.
Note Access to database tables is also affected by the table permission level property. See AdsDDSetTableProperty and the ADS_DD_TABLE_PERMISSION_LEVEL property.
Note The current user must be ADSSYS or have WITH GRANT permissions to grant permissions. See Advantage Data Dictionary User Permissions for more information.
After making a connection to the database, set up the access rights for the "Managers" user group to various tables and stored procedures. The user "rsmith" is then added to the "Managers" user group. Finally, access to the table "Salaries" is revoked from the user "rsmith" although he still has access to other managerial tables and views.
AdsConnect60( "n:\\MyData\\myData.ADD", ADS_REMOTE_SERVER, "ADSSYS", NULL, ADS_DEFAULT, &hDD );
/* Grant managers full access to the "employees" table. */
ulReturnCode = AdsDDGrantPermission( hDD, ADS_DD_TABLE_OBJECT, "Employees", NULL, "Managers",
ADS_PERMISSION_READ | ADS_PERMISSION_UPDATE | ADS_PERMISSION_INSERT |
ADS_PERMISSION_DELETE );
/* Grant managers full access to the "salaries" table */
ulReturnCode = AdsDDGrantPermission( hDD, ADS_DD_TABLE_OBJECT, "Salaries", NULL, "Managers",
ADS_PERMISSION_READ | ADS_PERMISSION_UPDATE | ADS_PERMISSION_INSERT |
ADS_PERMISSION_DELETE );
/* Grant managers the execution right to the "New Hire" store procedure */
ulReturnCode = AdsDDGrantPermission( hDD, ADS_DD_PROCEDURE_OBJECT, "New Hire", NULL, "Managers",
ADS_PERMISSION_INHERIT );
/* Add rsmith to the managers group. */
ulReturnCode = AdsDDAddUserToGroup( hDD, "Managers", "rsmith" );
/*
* rsmith inherits all rights from the managers group. However, rsmith is only an
* administrative assistant, so he is not allowed access to salary information.
* Therefore, revoke his inherited rights to the "salaries" table.
*/
ulReturnCode = AdsDDRevokePermission( hDD, ADS_DD_TABLE_OBJECT, "Salaries", NULL, "rsmith",
ADS_PERMISSION_INHERIT );
AdsDisconnect( hDD );