TRIPsystem Kernel API 8.3
Loading...
Searching...
No Matches
Group and User Administration

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.
 

Detailed Description

Administration of users and groups.

The group and user administration functions allows creation of group and user maintenance rouintes.

Function Documentation

◆ TdbAddMember()

int TdbAddMember ( const char *  group,
const char *  user 
)

Inserts a TRIP username into the membership list of a group.

Parameters
groupName of group to which the user is to be added
userName of user to add to the group
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

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.

Return Codes

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).
See also
TdbCreateUser()
TdbCreateGroup()
TdbDeleteMember()
TdbDeleteGroup()
TdbDeleteUser()

◆ TdbChangeFm()

int TdbChangeFm ( const char *  old_fm,
const char *  new_fm,
const char *  base 
)

Transfers ownership of a database from one user to another.

Parameters
old_fmName of existing owner (file manager) of the database.
new_fmName of new owner (file manager) of the database.
baseName of the database whose owner is being changed.
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIP user must possess the file manager (FM) privilege to execute this function.

Return Codes

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
See also
TdbSystemMode()

◆ TdbChangePassword()

int TdbChangePassword ( const char *  oldpass,
const char *  newpass 
)

Change password for the current user.

Parameters
oldpassOld password
newpassNew password
Returns
1 or other odd value on success, even value on error

Description

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.

Return Codes

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.
See also
TdbCreateUser()
TdbSetPassword()

◆ TdbChangeUm()

int TdbChangeUm ( const char *  old_um,
const char *  new_um,
const char *  user_group 
)

Change the user manager for a TRIP user or group.

Parameters
old_umThe name of the existing user manager responsible for the user or group.
new_umThe name of the new user manager responsible for the user or group.
user_groupUser or group name
Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIP user must possess the UM privilege to execute this function.

Return Codes

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.

◆ TdbCheckMember()

int TdbCheckMember ( const char *  group,
const char *  user 
)

Check a user for membership of a group.

Parameters
groupGroup name string
userUser name string
Returns
1 or other odd value on success, even value on error

Description

The function TdbCheckMember() checks whether or not the specified user is a member of the specified group.

Note
All users are members of the special group PUBLIC.

Parameter Values

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.

Privileges Required

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.

Return Codes

 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.
See also
TdbAddMember()
TdbCreateGroup()
TdbDeleteGroup()
TdbDeleteMember()

◆ TdbCreateGroup()

int TdbCreateGroup ( const char *  group)

Create a user group.

Parameters
groupGroup name string
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

The group parameter is passed a character string as the name of the group to be created.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Return Codes

 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.
See also
TdbAddMember()
TdbDeleteGroup()
TdbDeleteMember()

◆ TdbCreateUser()

int TdbCreateUser ( const char *  username,
const char *  password 
)

Create a new user.

Parameters
usernameName of user to be created
passwordPassword string
Returns
1 or other odd value on success, even value on error

Description

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.

Return Codes

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
See also
TdbChangePassword()
TdbDeleteUser()
TdbSetPassword()

◆ TdbDeleteGroup()

int TdbDeleteGroup ( const char *  group)

Delete a user group.

Parameters
groupName of group to be deleted
Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Return Codes

 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.

◆ TdbDeleteMember()

int TdbDeleteMember ( const char *  group,
const char *  user 
)

Delete a user from a group.

Parameters
groupGroup name string
userUser name string
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Return Codes

 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.

◆ TdbDeleteUser()

int TdbDeleteUser ( const char *  user)

Delete a TRIP user ID.

Parameters
userName of user to delete
Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Return Codes

 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.

◆ TdbGetGroup()

int TdbGetGroup ( char *  group,
int *  memberCount 
)
Parameters
groupName of group
memberCountNumber of members of group
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetGroup() loads the specified group record into main memory.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Return Codes

 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
See also
TdbGetMembers()

◆ TdbGetGroupName()

int TdbGetGroupName ( char *  groupName,
int  gid 
)

Get the group name for a group specified by number.

Parameters
groupNameGroup name
gidGroup identifier
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetGroupName() returns the group name for a group specified by the gid number.

Parameter Values

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.

Return Codes

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.

◆ TdbGetMembers()

int TdbGetMembers ( char *  members,
int *  length 
)

Retrieve the members of a group.

Parameters
membersNames of group member
lengthSize of members buffer
Returns
1 or other odd value on success, even value on error

Description

The function TdbGetMembers() retrieves all members of the group previously loaded by a call to TdbGetGroup(). Member names are separated by a zero byte.

Parameter Values

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.

Return Codes

 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
See also
TdbGetGroup()

◆ TdbGetUserProfile()

int TdbGetUserProfile ( char *  user,
user_profile_rec profile 
)

Retrieve the profile record for a TRIP user.

Parameters
userName of user
profileUser profile record
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege, be the SYSTEM user, or be the user who owns the object.

Return Codes

 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.
See also
TdbPutUserProfile()

◆ TdbGetUserRights()

int TdbGetUserRights ( const char *  user,
boolean *  UM,
boolean *  FM 
)

Retrieve the manager rights for a TRIP user.

Parameters
userName of user
UMUser manager rights flag
FMFile manager rights flag
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Privileges Required

The current TRIPsystem user must be the SYSTEM user.

Return Codes

 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
See also
TdbPutUserRights()

◆ TdbOsUser()

int TdbOsUser ( char *  OSuser,
int *  length 
)

Retrieve the current O/S user ID.

Parameters
OSuserOperating system user ID
lengthLength of operating system user ID.
Returns
1 or other odd value on success, even value on error

Description

The function TdbOsUser() returns the operating system user ID for the current TRIPsystem session.

Parameter Values

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.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.

◆ TdbPutUserProfile()

int TdbPutUserProfile ( user_profile_rec profileRecord)

Store the profile record for a TRIP user.

Parameters
profileRecordProfile record for user
Returns
1 or other odd value on success, even value on error

Description

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.

Privileges Required

The current TRIPsystem user must possess the user manager (UM) privilege to execute this function.

Any user is permitted to alter their own profile.

Return Codes

 Code Description Explanation
35043 User profile modified. Operation completed successfully.
9826 You are not a user manager
See also
TdbGetUserProfile()

◆ TdbPutUserRights()

int TdbPutUserRights ( boolean  UM,
boolean  FM 
)

Set the manager rights for a TRIP user.

Parameters
UMUser manager right
FMFile manager right
Returns
1 or other odd value on success, even value on error

Description

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 .

Parameter Values

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.

Privileges Required

The current TRIPsystem user must be the SYSTEM user.

Return Codes

 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.
See also
TdbGetUserRights()

◆ TdbSetPassword()

int TdbSetPassword ( const char *  user,
const char *  password 
)

Set a user password.

Parameters
userName of user
passwordNew password
Returns
1 or other odd value on success, even value on error

Description

The function TdbSetPassword() allows the TRIP System Manager to set the password of an existing TRIP user.

Parameter Values

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.

Privileges Required

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.

Return Codes

 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.

◆ TdbSystemMode()

int TdbSystemMode ( const char *  password)

Switch to TRIP System ID.

Parameters
passwordPassword string
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

 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.

◆ TdbTdbsUser()

int TdbTdbsUser ( char *  userName,
int *  length 
)

Retrieve the current TRIP user ID.

Parameters
userNameName of current TRIP user
lengthLength of user name
Returns
1 or other odd value on success, even value on error

Description

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.

Parameter Values

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.

Return Codes

This function always succeeds.

 Code Description Explanation
1 Operation completed successfully The function completed its operations without error.