Security

Modifies a file’s password, group ID, and permission mask.

Short Name

SECURITY()

Type

Server only

Declaration

COUNT Security(COUNT filno, pVOID bufptr, VRLEN bufsiz, COUNT mode)

Description

Security() permits the owner of a file to change a file’s security information, including the file’s password, Group ID, and permission mask. Security() permits members of the ADMIN group to change the default number of allowed consecutive logon failures or the default time to deny logon attempts after the failure limit is reached.

For file security changes to file number filno: bufptr points to the buffer containing the updated security information and bufsiz specifies the length of the buffer. The buffer should contain the old password, NULL terminated, immediately followed by the new information, also NULL terminated, which can be the new file password, new file group ID, new owner user ID, or the new permission mask. If you are changing the permission mask, the value following the NULL terminated old password must be a long integer containing the appropriate OR-ed permission values. To remove a password, simply pass a NULL byte for the new password. If you change the file owner, you will not be able to make additional calls to Security, only the new owner will be able to do so.

mode defines the type of request. The values for mode are:

Value	Symbolic Constant	Interpretation
1	SEC_FILEWORD	Change file password.
2	SEC_FILEGRUP	Change file group.
3	SEC_FILEMASK	Change file permission mask.
4	SEC_FILEOWNR	Change file owner.
5	SEC_FAIL_LIMIT	Set logon failure limit.
7	SEC_FAIL_TIME	Set logon failure time.
8	SEC_MUST_TIME	Set minimum time between logons.
9	SEC_BLOCK_NONADM	Block new logons except ADMIN group members.
10	SEC_BLOCK_NONSUP	Block new logons except ADMIN user ID.
11	SEC_BLOCK_OFF	Stop blocking new logons.
12	SEC_BLOCK_KILL	Block new logons except ADMIN user ID, suspend internal threads theads might open files, and kill any current connections and dumps.

filno is ignored when mode is SEC_FAIL_LIMIT, SEC_FAIL_TIME, or SEC_TEMPPW.

To establish a one-time password that another client can use, along with the user ID matching the caller that set the password, set bufptr to a special, (0x01 in first byte), one-time password and plen to the length of the password. filno is ignored. The password is available until it is used by the subsequent client with a matching user ID or the caller of Security logs off. The password set by the original caller MUST begin with a byte of value 0x01, otherwise it will be ignored.

To change the Logon Fail Limit in real time regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_LIMIT value. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

To change the time interval regardless of setting file or configuration file entries, point bufptr to a LONG holding the new LOGON_FAIL_TIME value in minutes. The value is stored in FAIRCOM.FCS and can only be changed by a subsequent call to Security or by replacing FAIRCOM.FCS. filno is ignored.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful open of ISAM files.
22	FNUM_ERR	File number is out of range.
47	FINT_ERR	c-tree Plus has not been initialized.
48	FMOD_ERR	Invalid mode value.
62	LERR_ERR	File must be opened exclusively.
153	VBSZ_ERR	Input does not match size of LONG.
447	BOWN_ERR	Only the user/owner can change the user/file password.
448	DEFP_ERR	File definition permission denied.
451	LPWD_ERR	The old password is not valid.
455	SGRP_ERR	The file owner does not belong to the new group.
580	FSEC_ERR	Negative value input.
584	LRSM_ERR	Logon fail limit exceeded, wait for timeout.
589	LADM_ERR	User not a member of the ADMIN group.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.