2. On Common Password to All Programs:
      PASSWORD *[,pswd$]

3. On Data File - Required:
      PASSWORD (chan[,ERR=stmtref]) pswd$ REQUIRED FOR OPEN

4. On Data File - Read Only:
      PASSWORD (chan[,ERR=stmtref]) pswd$ REQUIRED FOR WRITE

5. On Data File - Required & Encryption:
      PASSWORD (chan[,ERR=stmtref]) pswd$ REQUIRED FOR OPEN AND ON DATA

6. On Data File - Read Only & Encryption:
      PASSWORD (chan[,ERR=stmtref]) pswd$ REQUIRED FOR WRITE AND ON DATA

7.Copy Password to Data File from Data File
      PASSWORD (chan1[,ERR=stmtref]) FROM (chan2[,ERR=stmtref]) [,ERR=stmtref]

8. Remove Password from Data File:
      PASSWORD (chan[,ERR=stmtref]) pswd$ REMOVE

The formats described in this section assign/remove password protection on programs. Passworded programs cannot be listed or edited in ProvideX in any way unless the correct password is used.

PASSWORD pswd$

Apply to Program. To assign a password, load the program, enter the PASSWORD directive followed by the new password pswd$, then save the program;

For Example:

->LOAD "MYPROG"
->PASSWORD "CAT"
->SAVE "MYPROG"
->LOAD "MYPROG"
->LIST
Error #52 -- Program password protected
->DELETE 10
 
Error #52 -- Program password protected
->PASSWORD "CAT"
->LIST
0010 REM...
0020 ... etc.

Before changing a password, you must reload the program and enter the PASSWORD directive followed by the previously assigned password. At this point, you can either change the password by entering PASSWORD (again) followed by a new string, or remove password protection by entering PASSWORD (again) followed by a null string. PASSWORD *[,pswd$]

Apply Password Common to all Programs. Use the asterisk to denote a common password. ProvideX will apply a common password automatically to all previously passworded programs when they are loaded and to all new programs.

The formats described in this section assign password protection to data files. A KEY=pswd$ option is required to OPEN a passworded file. In order to define/change a password, you must have exclusive access to the file and it must be empty. The encryption feature is only available for VLR and EFF files.

Use one the following syntax formats to assign a password to a data file:

• PASSWORD (chan1[,ERR=stmtref]) pswd$ REQUIRED FOR OPEN
  Required for Open indicates that the correct password is always required on a open.

• PASSWORD (chan1[,ERR=stmtref]) pswd$ REQUIRED FOR WRITE
  Required for Write indicates that the correct password is required for write access, but it is not required for read-only access.

• PASSWORD (chan1[,ERR=stmtref]) pswd$ REQUIRED FOR OPEN AND ON DATA
  Required for Open and on Data indicates that the correct password is always required and that the data is encrypted.

• PASSWORD (chan1[,ERR=stmtref]) pswd$ REQUIRED FOR WRITE AND ON DATA
  Required for Write and on Data indicates that the correct password is required for write access but it is not required for read-only access, and that the data is encrypted.

The following table outlines the usage, access level, and encryption associated with each syntax format used to assign a password to a data file:.

Due to the fact that all key and data blocks are encrypted, routines that attempt to parse a passworded file in binary mode will not function correctly. This includes the file recovery utility *UFAR.

Prompting for Password

ProvideX includes a generic program called get_pswd that will prompt for a password when KEY= is invalid or missing when a passworded file is opened. ProvideX checks the existence of the get_pswdprogram in the *ext subdirectory first, and then in *ext/systemif the former is not found. This feature also allows the developer to customize the interface. As the prompt will be handled by a called program, it is also WindX-aware.

An embedded I/O (EIO) processing entry point called Get_Password provides the ability to prompt the user for a password based on logic associated with the EIO program. Provided the EIO program is valid and the entry point Get_Password exists, it will be used instead of the generic *ext/system/get_pswd or custom
*ext/get_pswd. As the file is not in an OPEN state at the point when the entry point is called, the LFO and LFA values do not contain meaningful information. For this reason, the name of the file will be passed in the fourth parameter, normally referred to as Value$.

Examples:

->KEYED "MyFile",[1:1:10],0,0
->OPEN LOCK (1)"MyFile"
->PASSWORD (1)"ABC" REQUIRED FOR OPEN
->CLOSE (1)
->OPEN (1,KEY="ABC")"MyFile"
->WRITE (1)"Record A"
->LOCK (1)
->PASSWORD (1)"XYZ" REQUIRED FOR OPEN Error #13: File access mode invalid
->PURGE (1)
->PASSWORD (1)"XYZ" REQUIRED FOR OPEN
->CLOSE (1)
->OPEN (1,KEY="XYZ")"MyFile"

Monitoring Attempts

TCB(68) reports the number of attempts which have been made to prompt for the password. This value is incremented prior to ProvideX calling the embedded I/O or get_pswdroutine so the first attempt will have a TCB(68) value of 1 (one).

By default, the first three attempts to access a passworded file using an invalid password will result in a prompt to re-enter the password. The fourth attempt generates an Error #53: Invalid password. This behaviour is controlled via the 'PP' System Parameter.

Password Error Reporting

The following error conditions will be trapped and reported:

PASSWORD (chan1[,ERR=stmtref]) FROM (chan2[,ERR=stmtref]) [,ERR=stmtref]

PASSWORD FROM allows a password from one file to be copied directly to another file without prompting the user for the password. Its use is primarily for rebuilding data files on the fly.

The maximum length for a file password is eight (8) characters, any data beyond that is simply ignored.

PASSWORD (chan) pswd$ REMOVE

This format removes password protection from a data file. In order to remove a password, you must have exclusive access to the file, and it must be empty.