TRIPsystem Kernel API 8.3
|
Administration of users and groups. More...
Functions | |
int | TdbAddMember (const char *group, const char *user) |
Inserts a TRIP username into the membership list of a group. | |
int | TdbChangeFm (const char *old_fm, const char *new_fm, const char *base) |
Transfers ownership of a database from one user to another. | |
int | TdbChangePassword (const char *oldpass, const char *newpass) |
Change password for the current user. | |
int | TdbChangeUm (const char *old_um, const char *new_um, const char *user_group) |
Change the user manager for a TRIP user or group. | |
int | TdbCheckMember (const char *group, const char *user) |
Check a user for membership of a group. | |
int | TdbCreateGroup (const char *group) |
Create a user group. | |
int | TdbCreateUser (const char *username, const char *password) |
Create a new user. | |
int | TdbDeleteGroup (const char *group) |
Delete a user group. | |
int | TdbDeleteMember (const char *group, const char *user) |
Delete a user from a group. | |
int | TdbDeleteUser (const char *user) |
Delete a TRIP user ID. | |
int | TdbGetGroup (char *group, int *memberCount) |
int | TdbGetGroupName (char *groupName, int gid) |
Get the group name for a group specified by number. | |
int | TdbGetMembers (char *members, int *length) |
Retrieve the members of a group. | |
int | TdbGetUserProfile (char *user, user_profile_rec *profile) |
Retrieve the profile record for a TRIP user. | |
int | TdbGetUserRights (const char *user, boolean *UM, boolean *FM) |
Retrieve the manager rights for a TRIP user. | |
int | TdbOsUser (char *OSuser, int *length) |
Retrieve the current O/S user ID. | |
int | TdbPutUserProfile (user_profile_rec *profileRecord) |
Store the profile record for a TRIP user. | |
int | TdbPutUserRights (boolean UM, boolean FM) |
Set the manager rights for a TRIP user. | |
int | TdbSetPassword (const char *user, const char *password) |
Set a user password. | |
int | TdbSystemMode (const char *password) |
Switch to TRIP System ID. | |
int | TdbTdbsUser (char *userName, int *length) |
Retrieve the current TRIP user ID. | |
Administration of users and groups.
The group and user administration functions allows creation of group and user maintenance rouintes.
int TdbAddMember | ( | const char * | group, |
const char * | user | ||
) |
Inserts a TRIP username into the membership list of a group.
group | Name of group to which the user is to be added |
user | Name of user to add to the group |
The user acquires access to any database previously granted to the group and will also be able to run procedures created for the group by the group's manager. A return code of 33091 will be given upon successful completion of the function.
Both the group and the user specified in the call must have been created previously using the functions TdbCreateGroup() and TdbCreateUser(). A return code of 9698 or 9634 will be given if the group or user has not been created.
All TRIP users are members of the special user group PUBLIC and so cannot be added to that group. A return code of 10178 will be given if an attempt is made to add a user name to the PUBLIC group.
The group
parameter is passed a string of characters as the name of the group to update.
The user
parameter is passed a string of characters as the name of the user to be added to the group.
The calling process must have user manager privilege and, further, must be the user manager of the group to which the user is being added. The calling process need not, however, be the manager of the user in question.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9634 | No such user as {username} | The user name passed in the user argument is unknown to the TRIP system. |
9698 | No such group as {groupname} | The group name passed in the group argument is unknown to the TRIPsystem. |
9730 | You are not the creator of the group {group}. | The filemanager calling this function is not the creator of the group named in the group argument. |
9826 | You are not a user manager | |
10178 | All users are members of the group | All user ids are automatically made members of the group PUBLIC when they are created. This error is returned if a deliberate attempt is made to add a user id to the PUBLIC group with a call to this function. |
10530 | {user} is already a member of {group}. | This error is returned when a subsequent attempt is made to add the named user to a group. |
33091 | User {user} is now a member of group {group} | This code is returned upon successful completion of this function (ADD MEMBER). |
int TdbChangeFm | ( | const char * | old_fm, |
const char * | new_fm, | ||
const char * | base | ||
) |
Transfers ownership of a database from one user to another.
old_fm | Name of existing owner (file manager) of the database. |
new_fm | Name of new owner (file manager) of the database. |
base | Name of the database whose owner is being changed. |
The user SYSTEM can transfer ownership of any database from one manager to another. Any other manager can only transfer the ownership of the databases that they own.
If the base argument is set to a single asterisk character (*), then all of the databases that belong to the old file manager will be transferred to the new owner.
The old_fm
parameter is passed a character string as the name of the current file manager for the database.
The new_fm
parameter is passed a character string as the name of the new file manager for the database.
The base
parameter is passed a character string as the name of the database whose owner is being changed.
The current TRIP user must possess the file manager (FM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
608 | Database {name} not found | The database named in the base parameter cannot be located for this user. |
9440 | You are not a SYSTEM manager | The TRIP username invoking this function is not a system manager. |
10400 | No such user as {name} | There is no user with the name in the string passed via the newFM parameter. |
10432 | There are no databases to transfer from {name} | There are no databases to transfer from the user named in the string passed via the oldFM parameter. |
16672 | The current and the new manager name are the same | The user names passed in the strings via the oldFM and newFM parameters identify the same user. |
17792 | You cannot change FM to the same user | You cannot change FM to the same user. |
21568 | All databases moved from {username1} to {username2}. | All the databases owned |
int TdbChangePassword | ( | const char * | oldpass, |
const char * | newpass | ||
) |
Change password for the current user.
oldpass | Old password |
newpass | New password |
This function allows the calling process to change the password of the current user. Only the SYSTEM user can change another user's password and to do so must call must call the TdbSetPassword() function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
6240 | Password must contain alphanumeric characters | The password string passed via new password contains characters other than the alphanumerics. |
7680 | Old password validation error | The password string passed via old password failed validation by the TRIPkernel. |
18720 | Password is changed | The requested password change has been completed successfully. |
int TdbChangeUm | ( | const char * | old_um, |
const char * | new_um, | ||
const char * | user_group | ||
) |
Change the user manager for a TRIP user or group.
old_um | The name of the existing user manager responsible for the user or group. |
new_um | The name of the new user manager responsible for the user or group. |
user_group | User or group name |
This function directs the transfer of an existing TRIP user or group from one user manager to another. Once the transfer is effected, the new user manager gains control of the user or group, and in the case of a group, any group procedures that were created before the transfer.
The user SYSTEM can transfer any user or group from one user manager to another. Any other user manager can transfer only those users or groups for which they are currently the manager.
If the name
argument is set to a single asterisk character (*), then all of the users that belong to the old manager will be transferred to the new manager.
The user SYSTEM, who owns all file and user managers, cannot transfer ownership for said users unless their file and/or user manager rights are first revoked. Consequently, only users without manager rights are transferred if an asterisk is specified as the object to be transferred from SYSTEM.
The current TRIP user must possess the UM privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
327*32 | {Name} is not a user manager | The user named in the string passed via newUM is not a user manager. |
10496 | UM {name} has not created any users | The user manager named in the string passed via the oldUM has not created any users. |
16448 | Ownership of the group PUBLIC cannot be changed | The ownership of the group PUBLIC cannot be changed. |
16544 | FM/UM managers cannot be transfered | FM/UM managers cannot be transfered. |
17760 | You cannot change UM to the same user | The username in the string passed via the newUM parameter is identical to the original user manager. |
22752 | UM changed to {username1} for {username2}. | The user manager for the requested user (passed via the name has been changed to the user named in the string passed via the newUM parameter. |
22784 | All users moved from {username1} to {username2} | The all users managed by the user named in the string passed via oldUM have been moved to the user named in the string passed via newUM. Names of the user managers are included in the error message returned. |
23872 | {number} FM/UM manager(s) have not been transfered | One or more users could not be transfered to the new user manager because they are themselves file- or user-managers. The error message text will include a count of the number of users affected. |
int TdbCheckMember | ( | const char * | group, |
const char * | user | ||
) |
Check a user for membership of a group.
group | Group name string |
user | User name string |
The function TdbCheckMember() checks whether or not the specified user is a member of the specified group.
The group
parameter is passed a character string as the name of the group of which membership is being checked.
The user
parameter is passed a character string as the name of the user whose membership is being checked.
All users can check their own group memberships, but to check the membership of other users, one has to be logged on as a user with UM (user manager) privileges.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9698 | No such group as group. | |
9824 | You are not a user manager | |
10498 | user is not a member of group. |
int TdbCreateGroup | ( | const char * | group | ) |
Create a user group.
group | Group name string |
The function TdbCreateGroup() creates a new user group with the name supplied, and adds an entry for this group to the data dictionary. The newly created group has no members and no access rights to databases. Use the function TdbAddMember() to add members to the group.
The group
parameter is passed a character string as the name of the group to be created.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
33059 | Group name created. | Command completed successfully. |
9824 | You are not a user manager | |
8770 | Username must be alphanumeric. | |
10146 | Already existing group. | |
10114 | Already existing user. | Attempt to create a group with the name like that of an existing user. |
int TdbCreateUser | ( | const char * | username, |
const char * | password | ||
) |
Create a new user.
username | Name of user to be created |
password | Password string |
This function creates a new user and adds an appropriate entry to the CONTROL file. The username and password assigned to the user are taken from the username and password parameters respectively. The newly created user has no manager rights or access to any databases. However, they will be able to use all PUBLIC procedures and those databases with access previously granted to the PUBLIC group.
Code | Description | Explanation |
---|---|---|
32963 | User {name} has access to the system. | Command completed successfully. |
9824 | You are not a user manager. | Only users who are user managers can create other users. |
16386 | Registered user quota ({maxusers}) exceeded. | The installed TRIPsystem licence does not allow any more users to be created. |
8770 | Username must be alphanumeric. | |
6722 | Password must contain alphanumeric characters. | |
10146 | Already existing group. | |
10114 | Already existing user. | Attempt to create a user with the name like that of an existing user or group |
int TdbDeleteGroup | ( | const char * | group | ) |
Delete a user group.
group | Name of group to be deleted |
The function TdbDeleteGroup() removes the specified group from CONTROL if the calling process is registered as the owner of the group in question. The call also deletes any procedures and database access rights associated with the group.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
33155 | Group name is deleted. | |
9824 | You are not a user manager | |
15170 | The group PUBLIC cannot be deleted. | |
9698 | No such group as group. | |
9730 | You are not the creator of the group group. |
int TdbDeleteMember | ( | const char * | group, |
const char * | user | ||
) |
Delete a user from a group.
group | Group name string |
user | User name string |
The function TdbDeleteMember() deleted the username as passed via the user
parameter from the group named in the group
parameter. The TRIPsystem user ID for the current session must be the user manager of the group from which the user is being deleted, but need not be the creator of the user. All TRIP users are members of the group PUBLIC, and so cannot be added to, or removed from that group. The routine removes the specified TRIP user ID from the member list for the specified TRIP user group. The user ceases to be a member of the group, and loses any database or procedure access which he or she enjoyed exclusively because of his or her membership of the group.
The group
parameter is passed a character string as the name of the group from which the user is to be deleted.
The user
parameter is passed a character string as the name of the user to be deleted from the group.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
33184 | User username is no longer a member of group groupname. | Operation completed successfully. |
9824 | You are not a user manager | |
9698 | No such group as group. | |
9730 | You are not the creator of the group group. | |
9634 | No such user as username. | |
10178 | All users are members of the group PUBLIC | |
10210 | Members of the group PUBLIC cannot be deleted. | |
10498 | user is not a member of group. |
int TdbDeleteUser | ( | const char * | user | ) |
Delete a TRIP user ID.
user | Name of user to delete |
The function TdbDeleteUser() deletes the specified user from the CONTROL file. It also deletes any procedures owned by the user. The TRIPsystem user ID for the current session must be the owner of the TRIP user ID to be deleted.
The user ID to be deleted must not be the current manager for either any existing TRIP users or databases. Thus if the user to be deleted has user manager rights within the TRIP system, any objects created by the user must first be transferred to some other user manager. Similarly, the ownership of any databases currently managed by the user must be transferred to another file manager. The CONTROL file records for the groups in which the user was formerly a member are updated to remove the user membership link.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
32931 | User name has lost access to the system. | Operation completed successfully. |
9826 | You are not a user manager. | The logged on user must have user manager privileges in order to delete users. |
9634 | No such user as user. | Attempt to delete a user that does not exist. |
10274 | You have not created this user. | A user can only be deleted by its creator. |
8930 | User manager with existing users/groups cannot be deleted. | A user who is a user manager can not be deleted while there remains user created by this user manager. |
8962 | File manager with existing databases cannot be deleted. | The owner of existing databases cannot be deleted. |
int TdbGetGroup | ( | char * | group, |
int * | memberCount | ||
) |
group | Name of group |
memberCount | Number of members of group |
The function TdbGetGroup() loads the specified group record into main memory.
The group
parameter is passed a character string as the name of group to be retrieved.
The memberCount
parameter receives the number of members of the specified group.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9826 | You are not a user manager. | The logged on user must have user manager privileges in order to delete users. |
9730 | You are not the creator of the group group. | |
9698 | No such group as group. | |
10178 | All users are members of the group PUBLIC |
int TdbGetGroupName | ( | char * | groupName, |
int | gid | ||
) |
Get the group name for a group specified by number.
groupName | Group name |
gid | Group identifier |
The function TdbGetGroupName() returns the group name for a group specified by the gid
number.
The groupName
parameter is passed a string buffer that receives the name of the group to be retrieved. This buffer must be at least 128 bytes in size.
The gid
parameter is passed the group identification number of the group to be retrieved.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbGetMembers | ( | char * | members, |
int * | length | ||
) |
Retrieve the members of a group.
members | Names of group member |
length | Size of members buffer |
The function TdbGetMembers() retrieves all members of the group previously loaded by a call to TdbGetGroup(). Member names are separated by a zero byte.
The members
parameter is passed a string buffer that receives the names of the members of the selected group.
On input, the length
is to be assigned the size of the members
buffer. On output, it receives a count of the number of bytes written to the members
buffer.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
3 | Operation completed successfully, but there is more data to fetch by repeated calls to this function. | |
9826 | You are not a user manager |
int TdbGetUserProfile | ( | char * | user, |
user_profile_rec * | profile | ||
) |
Retrieve the profile record for a TRIP user.
user | Name of user |
profile | User profile record |
The function TdbGetUserProfile() reads the user profile record for the specified user from the CONTROL file. This user profile record contains two types of information about the user. The first type is informational only (e.g. telephone number and address), and does not affect the behavior of the system. The second type of information (e.g. preferred date format and start module) can be used to modify the behavior of the TRIP system.
A user profile record can only be obtained by the user to which it belongs, the owner of the user, and user SYSTEM.
The user
parameter is passed a character string as the name of the user whose profile is retrieved.
The profile
is passed a user profile record to receive the profile record for the named user.
The current TRIPsystem user must possess the user manager (UM) privilege, be the SYSTEM user, or be the user who owns the object.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9634 | No such user as username. | |
9826 | You are not a user manager | |
10690 | You are not the creator of user name. |
int TdbGetUserRights | ( | const char * | user, |
boolean * | UM, | ||
boolean * | FM | ||
) |
Retrieve the manager rights for a TRIP user.
user | Name of user |
UM | User manager rights flag |
FM | File manager rights flag |
The function TdbGetUserRights() returns the user and file manager rights for the TRIP user ID supplied. The user name is passed via the user
parameter and the user manager and file manager rights are returned in the UM
and FM
parameters respectively. Note that a TRIPsystem user group cannot have manager rights, and hence this routine must have a TRIPsystem user ID as the value of the user
parameter.
The user
parameter is passed a character string as the name of the user whose rights are retrieved.
The UM
parameter is passed a byte to receive the user manager rights of the user. The lowest bit set indicates that the user has user manager rights within the TRIP system; if this bit is clear, the user has no user manager rights.
The FM
parameter is passed a byte to receive the file manager rights of the user. The lowest bit set indicates that the user has file manager rights within the TRIP system; if this bit is clear, the user has no file manager rights.
The current TRIPsystem user must be the SYSTEM user.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
9634 | No such user as username | |
9666 | User id id is a group id. | |
9826 | You are not a user manager |
int TdbOsUser | ( | char * | OSuser, |
int * | length | ||
) |
Retrieve the current O/S user ID.
OSuser | Operating system user ID |
length | Length of operating system user ID. |
The function TdbOsUser() returns the operating system user ID for the current TRIPsystem session.
The OSuser
parameter is passed a character string to receive the name of the operating system user ID for the current session.
The length
parameter is passed a pointer to an int
variable to receive the length of the returned operating system user ID.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
int TdbPutUserProfile | ( | user_profile_rec * | profileRecord | ) |
Store the profile record for a TRIP user.
profileRecord | Profile record for user |
The function TdbPutUserProfile() writes into the CONTROL file the user profile record for the specified user. The calling process needs TRIPsystem user manager rights (if it is not his/her own profile). The profile record contains information about the user which is of two types. The first type is informational only, and does not affect the behavior of the system. The second type of information stored in the user profile record can be used to modify the behavior of the TRIP system.
The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.
Any user is permitted to alter their own profile.
Code | Description | Explanation |
---|---|---|
35043 | User profile modified. | Operation completed successfully. |
9826 | You are not a user manager |
int TdbPutUserRights | ( | boolean | UM, |
boolean | FM | ||
) |
Set the manager rights for a TRIP user.
UM | User manager right |
FM | File manager right |
The function TdbPutUserRights() uses the TRIP user ID previously loaded with a call to the function TdbGetUserRights(), and records the new user and file manager rights for this user in the CONTROL file.
File and user manager rights can only be granted and revoked by user SYSTEM. When a user is given manager rights, the ownership of that user is automatically transferred to SYSTEM .
The UM
parameter is passed a single byte as a flag to indicate the setting of the user manager rights for the user being checked. The lowest bit set indicates that the user has user manager rights within the TRIP system; if this bit is clear, the user has no user manager rights.
The FM
parameter is passed a single byte as a flag to indicate the setting of the file manager rights for the user being checked. The lowest bit set indicates that the user has file manager rights within the TRIP system; if this bit is clear, the user has no file manager rights.
The current TRIPsystem user must be the SYSTEM user.
Code | Description | Explanation |
---|---|---|
38627 | User name now has FM manager rights. | Success. File manager rights granted. |
38659 | User name now has UM manager rights. | Success. User manager rights granted. |
38691 | User name now has FM and UM manager rights. | Success. User and file manager rights granted. |
38723 | User name now has no manager rights. | Success. Manager rights revoked |
9922 | You are not a SYSTEM manager. | |
7362 | Manager rights of the user SYSTEM cannot be changed. | |
11714 | FM rights cannot be revoked if own databases exists. | File manager rights cannot be revoked for a user who owns a database. |
11746 | UM rights cannot be revoked if own users/groups exists. | User manager rights cannot be revoked for a user who owns users or groups. |
int TdbSetPassword | ( | const char * | user, |
const char * | password | ||
) |
Set a user password.
user | Name of user |
password | New password |
The function TdbSetPassword() allows the TRIP System Manager to set the password of an existing TRIP user.
The user
parameter is passed a character string as the name of the user whose password is being set.
The password
parameter is passed a character string as the new password string for the user.
From version 4 of TRIP, any user who has user manager (UM) rights may use this function. For older versions of TRIP, the current user must be the SYSTEM user.
Code | Description | Explanation |
---|---|---|
32163 | Password is changed. | Operation completed successfully. |
9922 | You are not a SYSTEM manager. | |
6722 | Password must contain alphanumeric characters. | |
9634 | No such user as username. | |
9762 | You are not the creator of this record. |
int TdbSystemMode | ( | const char * | password | ) |
Switch to TRIP System ID.
password | Password string |
The function TdbSystemMode() is used to temporarily switch the current session from the logged in TRIP user ID to that of the TRIP system manager. A call to this routine with the correct system managers password will grant the calling process user, file and system manager rights within the current session. A subsequent call to the routine with an empty password will cause the rights of the current session to revert to those of the logged in TRIP user ID.
The password
parameter is passed a character string as the password for the TRIP user SYSTEM. If the password has zero length then the TRIP will revert to the original user.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |
10242 | Invalid password. | The supplied password did not match that of the user SYSTEM. |
int TdbTdbsUser | ( | char * | userName, |
int * | length | ||
) |
Retrieve the current TRIP user ID.
userName | Name of current TRIP user |
length | Length of user name |
The function TdbTdbsUser() returns the TRIP ID for the current TRIP session, i.e. the logged in TRIP user name which was used in the call to the TdbCheckUser() function.
The userName
parameter is passed a character string to receive the name of the current TRIP user.
The length
parameter is passed a pointer to an int
variable to receive the count of the number of bytes in the returned user name.
This function always succeeds.
Code | Description | Explanation |
---|---|---|
1 | Operation completed successfully | The function completed its operations without error. |