1 05/16/16 input_history_
2
3 Function: The input_history_ I/O module passes-thru I/O operations
4 to a monitored switch. For a get_line operation, it captures the
5 line returned by the monitored switch in a history file, before
6 returning it to the caller.
7
8 If the monitored switch is attached to the window_io_ module, then
9 the window_io_ real-time input line editor is augmented with editing
10 requests to search the history file for past input lines to
11 re-enter. See "Notes on video editing" below.
12
13 Use the input_history command to facilitate attachment of the
14 input_history_ I/O module. See: input_history.info or: ih.info
15
16
17 Syntax:
18 input_history_ monitored_switch_name -control_args
19
20
21 Notes on attach description:
22 monitored_switch_name
23 is the name of an I/O switch whose input lines are captured. It
24 must be attached to an I/O module open with an opening mode of
25 stream_input or stream_input_output.
26
27 -pathname PATH, -pn PATH
28 use PATH as the location of the history file. The default PATH is:
29 homedir>user name.history
30 -perprocess, -pp
31 use a temporary history file created in the process directory.
32 -permanent, -perm
33 use only a permanent the history file. See "Notes on the history
34 file" for further information on these three control arguments.
35
36
37 -lines N, -ln N
38 recommends a size for the history file, in lines. The default is
39 200 lines about 2 records of storage if the average input line is
40 40 characters in length. See "Notes on the history file" below.
41 -truncate, -tc
42 if the history file already exists, truncates this file as part of
43 the attach operation. The default is to extend the existing file.
44
45
46 Notes on the history file:
47 Past input lines are logged in the history file as a stream of
48 characters. The file bit count is adjusted after each line is
49 appended. This permits searching or examining the file: using the
50 print command or a file editor; or using video editing functions added
51 to the window_io_ line editor by the input_history_ module. See
52 "Notes on video editing" below.
53
54
55 Permanent history file
56 Holds a log of past input lines, and remains in the file system
57 after the process ends. A subsequent process may log additional
58 input lines in this file, and may select and re-input lines from
59 the earlier process.
60
61 Temporary history file
62 Holds input lines only for the current process. The user may
63 select and re-input lines while this process runs. However, the
64 file is deleted when the process ends.
65
66
67 One process per history file
68 Several processes may not share the same history file concurrently.
69 For each permanent history file XXX.history, a corresponding
70 process identity file XXX.hisLock records the lock_id of the
71 process using that history file. While that process is running,
72 input_history_ prevents another process from attaching with that
73 file.
74
75 Read/write access required
76 The process must have read/write access to attach using an existing
77 history file. An access error might occur if using a file created
78 by another user or group; or created by a process with an access
79 class that differs from the current process authorization.
80
81
82 Permanent history file attach error
83 If a permanent history file cannot be reused due to locking or
84 access error, either: a temporary history file is created; or if
85 -permanent was given, then an error is reported and the attach
86 operation fails. If both -pathname and -perprocess are given, then
87 a temporary file is created only when the file given with -pathname
88 is locked or inaccessible. If the permanent history file was
89 locked, the temporary file is initialized by copying the permanent
90 file.
91
92 Requiring a temporary history file
93 If -perprocess is given without a -pathname, then a temporary file
94 is always created.
95
96
97 Automatic purging of oldest input
98 When a history file reaches its recommended size of N lines see
99 the -lines attach argument, the oldest lines are removed from the
100 top of the file to permit new lines to be appended to the end of
101 the file. These scroll operations are grouped into page-size
102 chunks, to avoid excessive overhead during each input operation.
103 Thus, the file may actually contain N-lines, plus some additional
104 lines.
105
106
107 Notes on video editing:
108 When the input_history_ I/O module is attached, several editing
109 requests are added to the window_io_ input line editor. The
110 previous-line ^P and next-line ^N requests accept numeric
111 repetition counts e.g. ESC 7 ^P to move back 7 lines; or ^U ^N to
112 move forward 4 lines.
113
114 ^P
115 Select the previous line in the history file for editing and
116 re-input.
117 ^N
118 Select the next line in the history file for editing and re-input.
119 ^G
120 Abort selection of a prior input line. Original line is again on
121 display in the window_io_ line editor.
122
123
124 Incremental searches of the input history are started using one of the
125 following requests.
126
127 ^R
128 Perform an incremental search backward in the history file, looking
129 for a line that matches characters typed following ^R.
130 ^S
131 Perform an incremental search forward in the history file, looking
132 for a line that matches characters typed following ^S.
133
134
135 As each character is added to the incremental search string, the
136 history line matching the search string is displayed.
137
138 Backspace, DEL, or # your erase character
139 Remove a character from the incremental search string to undo
140 part of the search operation. Different characters may then be
141 added to the search string.
142
143 Incremental searching ends with one of the following characters.
144 ESC
145 Matching line returned to window_io_ line editor for editing and
146 re-input.
147 ^G
148 Incremental search is aborted as described in ^G request above.
149
150
151 other window_io_ line editor control key
152 The selected input line is returned to window_io_ line editor;
153 the window_io_ edit function bound to the given control key is
154 then applied to the selected line. Two of the many window_io_
155 requests that can be applied are listed below.
156
157 RETURN ^M, NL ^J
158 The selected history line is re-input, as is.
159
160 ^E
161 Move to end of the selected line, where further edit requests
162 may be applied to the line.
163
164
165 Notes on the open operation:
166 Because input_history_ is a monitoring-style I/O module, most I/O
167 operations pass-thru directly to the monitored switch. For this
168 reason, the open operation for input_history_ is performed
169 automatically at attach time. It uses the same opening mode as the
170 monitored switch.
171
172
173 Notes on other operations:
174 Put Chars Operation
175 is a pass-thru to the monitored I/O module.
176 Get Chars Operation
177 is a pass-thru to the monitored I/O module.
178 Get Line Operation
179 This is primarily a pass-thru to the monitored I/O module.
180 However, any lines or partially-read line fragments are logged in
181 the history file before returning the input to the caller.
182
183
184 Modes Operation
185 is a pass-thru to the monitored I/O module. input_history_ has no
186 modes of its own.
187 Position Operation
188 is a pass-thru to the monitored I/O module.
189 Control Operation
190 is primarily a pass-thru to the monitored I/O module. However, the
191 following input_history_ control operations are also supported.
192
193 get_input_history_lines
194 returns the current recommended size for the history file, in
195 lines.
196 set_input_history_lines N
197 gives a value for the recommended size for the history file,
198 in lines.