1 02/08/84  read_password_
 2 
 3 
 4 Entry points in read_password_:
 5    (List is generated by the help command)
 6 
 7 
 8 :Entry: read_password_: 02/08/84  read_password_
 9 
10 Function: reads a single line from the users' terminal (actually from
11 the user_input I/O switch).  It attempts to hide the input line by
12 turning the printing mechanism off before reading and turning it back
13 on afterwards.  If the printing mechanism cannot be turned off, then a
14 mask consisting of several layers of printing designed to "black out"
15 the page is printed.  One of the layers of printing is pseudo-randomly
16 generated so that it will be different each time the subroutine is
17 called, thus making it difficult to analyze the layers of
18 overprinting.  The mask is 12 characters long.
19 
20 
21 Syntax:
22 declare read_password_ entry (char(*), char(*));
23 call read_password_ (prompt, password);
24 
25 
26 Arguments:
27 prompt
28    is a message to be printed before the password is read.  It can be
29    any length.  A newline character is always printed after the
30    prompting message.  (Input)
31 password
32    is the password that the user typed.  It can be up to 120 characters
33    long.  (Output)
34 
35 
36 Notes:  The password is processed as follows -- tab characters are
37 translated to blanks.  Leading blanks are removed.  Characters after
38 any embedded blanks are removed.  If the resulting password is all
39 blank, a single asterisk ("*") is returned, otherwise the password is
40 returned.
41 
42 
43 :Entry:  switch:  02/08/84 read_password_$switch
44 
45 
46 Function:  This entry is similar to read_password_, but it allows the
47 caller to specify the I/O switches to be used to print the prompt and
48 read the password.
49 
50 
51 Syntax:
52 declare read_password_$switch entry (ptr, ptr, char(*), char(*),
53      fixed bin(35));
54 call read_password_$switch (output_switch, input_switch, prompt,
55      password, code);
56 
57 
58 Arguments:
59 output_switch
60    is a pointer to the I/O switch on which the prompt, and if necessary
61    the password mask, is printed.  (Input)
62 input_switch
63    is a pointer to the I/O switch from which the password is read.
64    (Input)
65 prompt
66    is a message to be printed before the password is read.  It can be
67    any length.  A newline character is always printed after the
68    prompting message.  (Input)
69 
70 
71 password
72    is the password that the user typed.  It can be up to 120 characters
73    long.  (Output)
74 code
75    is a standard system status code which is non-zero only if a
76    password could not be read.  (Output)
77 
78 
79 Notes:  The password is processed as follows -- tab characters are
80 translated to blanks.  Leading blanks are removed.  Characters after
81 any embedded blanks are removed.  If the resulting password is all
82 blank, a single asterisk ("*") is returned; otherwise the password is
83 returned.