facility.tex 34.5 KB
Newer Older
1 2
% !TeX root = forth.tex

3 4 5 6 7 8 9 10 11 12
\chapter{The optional Facility word set} % 10
\wordlist{facility}

\section{Introduction} % 10.1

\section{Additional terms and notation} % 10.2
None.

\section{Additional usage requirements} % 10.3

pknaggs's avatar
pknaggs committed
13

pknaggs's avatar
pknaggs committed
14 15
\subsection{Data types} % 10.3.1

16
Append table \ref{facility:types} to table \ref{table:datatypes}.
pknaggs's avatar
pknaggs committed
17 18 19 20 21 22 23 24 25

\begin{table}[h]
  \begin{center}
	\caption{Data types}
	\label{facility:types}
	\begin{tabular}{llr}
	\hline\hline
	\emph{Symbol} & \emph{Data type} & \emph{Size on stack} \\
	\hline
26 27 28
	\emph{struct-sys}
	& data structures
	& implementation dependent \\
pknaggs's avatar
pknaggs committed
29 30 31 32 33 34 35
	\hline\hline
	\end{tabular}
  \end{center}
\end{table}

\subsubsection{Structure type} % 10.3.1.1

36 37 38
The implementation-dependent data generated upon beginning to compile
a \word{BEGIN-STRUCTURE} {\ldots} \word{END-STRUCTURE} structure and
consumed at its close is represented by the symbol \param{struct-sys}
pknaggs's avatar
pknaggs committed
39
throughout this standard.
pknaggs's avatar
pknaggs committed
40 41

\subsubsection{Character types} % 10.3.1.2
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
Programs that use more than seven bits of a character by
\word{EKEY} have an environmental dependency.

See: \xref[3.1.2 Character types]{usage:char}.


\section{Additional documentation requirements} % 10.4

\subsection{System documentation} % 10.4.1

\subsubsection{Implementation-defined options} % 10.4.1.1

\begin{itemize}
\item encoding of keyboard events \wref{facility:EKEY}{EKEY});
\item duration of a system clock tick;
\item repeatability to be expected from execution of
	\wref{facility:MS}{MS}.
\end{itemize}

\subsubsection{Ambiguous conditions} % 10.4.1.2

\begin{itemize}
\item \wref{facility:AT-XY}{AT-XY} operation can't be performed on
pknaggs's avatar
pknaggs committed
65
	user output device;
pknaggs's avatar
pknaggs committed
66

67
\item A \param{name} defined by
pknaggs's avatar
pknaggs committed
68
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}
pknaggs's avatar
pknaggs committed
69
	is executed before the corresponding \linebreak
pknaggs's avatar
pknaggs committed
70
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}
71
	has been executed.
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
\end{itemize}

\subsubsection{Other system documentation} % 10.4.1.3

\begin{itemize}
\item no additional requirements.
\end{itemize}

\subsection{Program documentation} % 10.4.2

\subsubsection{Environmental dependencies} % 10.4.2.1

\begin{itemize}
\item using more than seven bits of a character in
	\wref{facility:EKEY}{EKEY}.
\end{itemize}

\subsubsection{Other program documentation} % 10.4.2.2

\begin{itemize}
\item no additional requirements.
\end{itemize}

\section{Compliance and labeling} % 10.5

pknaggs's avatar
pknaggs committed
97
\subsection{Forth-\snapshot{} systems} % 10.5.1
98 99 100 101 102 103 104 105 106 107 108 109 110

The phrase ``Providing the Facility word set'' shall be appended to
the label of any Standard System that provides all of the Facility
word set.

The phrase ``Providing \emph{name(s)} from the Facility Extensions
word set'' shall be appended to the label of any Standard System
that provides portions of the Facility Extensions word set.

The phrase ``Providing the Facility Extensions word set'' shall be
appended to the label of any Standard System that provides all of
the Facility and Facility Extensions word sets.

pknaggs's avatar
pknaggs committed
111
\subsection{Forth-\snapshot{} programs} % 10.5.2
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

The phrase ``Requiring the Facility word set'' shall be appended to
the label of Standard Programs that require the system to provide
the Facility word set.

The phrase ``Requiring \emph{name(s)} from the Facility Extensions
word set'' shall be appended to the label of Standard Programs that
require the system to provide portions of the Facility Extensions
word set.

The phrase ``Requiring the Facility Extensions word set'' shall be
appended to the label of Standard Programs that require the system
to provide all of the Facility and Facility Extensions word sets.

\section{Glossary} % 10.6

\subsection{Facility words} % 10.6.1

\begin{worddef}{0742}{AT-XY}[at-x-y]
\item \stack{u_1 u_2}{}

	Perform implementation-dependent steps so that the next
	character displayed will appear in column \param{u_1}, row
	\param{u_2} of the user output device, the upper left corner
	of which is column zero, row zero. An ambiguous condition exists
	if the operation cannot be performed on the user output device
	with the specified parameters.
\end{worddef}


\begin{worddef}[KEYq]{1755}{KEY?}[key-question]
\item \stack{}{flag}

	If a character is available, return \emph{true}. Otherwise,
	return \emph{false}. If non-character keyboard events are
	available before the first valid character, they are discarded
	and are subsequently unavailable. The character shall be
	returned by the next execution of \word[core]{KEY}.

	After \word{KEYq} returns with a value of \emph{true},
	subsequent executions of \word{KEYq} prior to the execution
	of \word[core]{KEY} or \word{EKEY} also return \emph{true},
	without discarding keyboard events.

pknaggs's avatar
pknaggs committed
156
\see \rref{facility:KEYq}{}.
157

pknaggs's avatar
pknaggs committed
158
	\begin{rationale} % A.10.6.1.1755 KEY?
pknaggs's avatar
pknaggs committed
159
		The committee has gone around several times on the
160 161 162 163 164 165 166 167
		stack effects. Whatever is decided will violate somebody's
		practice and penalize some machine. This way doesn't interfere
		with type-ahead on some systems, while requiring the
		implementation of a single-character buffer on machines where
		polling the keyboard inevitably results in the destruction of
		the character.

		Use of \word[core]{KEY} or \word{KEYq} indicates that the
pknaggs's avatar
pknaggs committed
168
		application does not wish to process non-character events,
169 170 171 172 173 174 175 176
		so they are discarded, in anticipation of eventually receiving
		a valid character. Applications wishing to handle non-character
		events must use \word{EKEY} and \word{EKEYq}. It is possible
		to mix uses of \word{KEYq}/\word[core]{KEY} and
		\word{EKEYq}/\word{EKEY} within a single application, but
		the application must use \word{KEYq} and \word[core]{KEY} only
		when it wishes to discard non-character events until a valid
		character is received.
pknaggs's avatar
pknaggs committed
177
	\end{rationale}
178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
\end{worddef}

\begin{worddef}{2005}{PAGE}
\item \stack{}{}

	Move to another page for output. Actual function depends on the
	output device. On a terminal, \word{PAGE} clears the screen and
	resets the cursor position to the upper left corner. On a
	printer, \word{PAGE} performs a form feed.
\end{worddef}


\subsection{Facility extension words} % 10.6.2
\extended

pknaggs's avatar
pknaggs committed
193 194
% -------------------------------------

pknaggs's avatar
pknaggs committed
195
\begin{worddef}{0135}{+FIELD}[plus-field][X:structures]
pknaggs's avatar
pknaggs committed
196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211
\item \stack{n_1 n_2 "<spaces>name"}{n_3}

	Skip leading space delimiters.  Parse \param{name} delimited
	by a space.  Create a definition for \param{name} with the
	execution semantics defined below.  Return \param{n_3} =
	\param{n_1} + \param{n_2} where \param{n_1} is the offset
	in the data structure before \word{+FIELD} executes, and
	\param{n_2} is the size of the data to be added to the data
	structure. \param{n_1} and \param{n_2} are in address units.

\execute[name]
	\stack{addr_1}{addr_2}

	Add \param{n_1} to \param{addr_1} giving \param{addr_2}.

\see \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE},
pknaggs's avatar
pknaggs committed
212 213
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\
	\wref{facility:CFIELD:}{CFIELD:},
pknaggs's avatar
pknaggs committed
214
	\wref{facility:FIELD:}{FIELD:},
pknaggs's avatar
pknaggs committed
215
	\wref{floating:FFIELD:}{FFIELD:}, \\
pknaggs's avatar
pknaggs committed
216
	\wref{floating:SFFIELD:}{SFFIELD:},
pknaggs's avatar
pknaggs committed
217
	\wref{floating:DFFIELD:}{DFFIELD:},
pknaggs's avatar
pknaggs committed
218
	\rref{facility:+FIELD}{}.
pknaggs's avatar
pknaggs committed
219

pknaggs's avatar
pknaggs committed
220
	\begin{rationale} % A.10.6.2.---- +FIELD
pknaggs's avatar
pknaggs committed
221
		\word{+FIELD} is not required to align items.  This is
222
		deliberate and allows the construction of unaligned data
pknaggs's avatar
pknaggs committed
223 224 225 226
		structures for communication with external elements such
		as a hardware register map or protocol packet.
		Field alignment has been left to the appropriate
		\emph{x}\texttt{FIELD:} definition.
pknaggs's avatar
pknaggs committed
227
	\end{rationale}
pknaggs's avatar
pknaggs committed
228

pknaggs's avatar
pknaggs committed
229 230
	\begin{implement} % I.10.6.2.---- +FIELD
		\textdf{Create a new field within a structure definition
pknaggs's avatar
pknaggs committed
231 232
			of size \param{n} bytes.}

233
		\word{:} +FIELD\tab\word{bs} n <"name"> -{}- ; Exec: addr -{}- 'addr \\
pknaggs's avatar
pknaggs committed
234 235 236
		\tab \word{CREATE} \word{OVER} \word{,} \word{+} \\
		\tab \word{DOES} \word{@} \word{+} \\
		\word{;}
pknaggs's avatar
pknaggs committed
237
	\end{implement}
pknaggs's avatar
pknaggs committed
238
\end{worddef}
pknaggs's avatar
pknaggs committed
239 240


pknaggs's avatar
pknaggs committed
241
\begin{worddef}{0763}{BEGIN-STRUCTURE}[][X:structures]
pknaggs's avatar
pknaggs committed
242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257
\item \stack{"<spaces>name"}{struct-sys 0}

	Skip leading space delimiters. Parse \param{name} delimited
	by a space. Create a definition for \param{name} with the
	execution semantics defined below.  Return a \param{struct-sys}
	(zero or more implementation dependent items) that will be
	used by \word{END-STRUCTURE} and an initial offset of 0.

\execute[name]
	\stack{}{+n}

	\param{+n} is the size in memory expressed in address units of
	the data structure.  An ambiguous condition exists if
	\param{name} is executed prior to the associated
	\word{END-STRUCTURE} being executed.

pknaggs's avatar
pknaggs committed
258
\see \wref{facility:+FIELD}{+FIELD},
pknaggs's avatar
pknaggs committed
259
	\wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\
pknaggs's avatar
pknaggs committed
260
	\rref{facility:BEGIN-STRUCTURE}{}.
261

pknaggs's avatar
pknaggs committed
262

pknaggs's avatar
pknaggs committed
263
	\begin{rationale} % A.10.6.2.---- BEGIN-STRUCTURE
264
		There are two schools of thought regarding named data
pknaggs's avatar
pknaggs committed
265 266 267 268 269 270
		structures: name first and name last.  The name last
		school can define a named data structure as follows:

		\begin{quote}\ttfamily
		0 \tab[11.5] \word{bs} initial total byte count \\
		\tab 1 \word{CELLS} \word{+FIELD} p.x	\tab \word{bs} A single cell filed named p.x \\
271 272
		\tab 1 \word{CELLS} \word{+FIELD} p.y   \tab \word{bs} A single cell field named p.y \\
		\word{CONSTANT} point \tab[3.8] \word{bs} save structure size
pknaggs's avatar
pknaggs committed
273 274 275 276 277 278
		\end{quote}

		While the name first school would define the same data
		structure as:

		\begin{quote}\ttfamily
279 280 281
		\word{BEGIN-STRUCTURE} point \tab[-.3] \word{bs} create the named structure \\
		\tab 1 \word{CELLS} \word{+FIELD} p.x	\tab \word{bs} A single cell filed named p.x \\
		\tab 1 \word{CELLS} \word{+FIELD} p.y   \tab \word{bs} A single cell field named p.y \\
pknaggs's avatar
pknaggs committed
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
		\word{END-STRUCTURE}
		\end{quote}

		Although many systems provide a name first structure there
		is no common practice to the words used.  The words
		\word{BEGIN-STRUCTURE} and \word{END-STRUCTURE} have been
		defied as a means of providing a portable notation that does
		not conflict with existing systems.

		The field defining words (\emph{x}\texttt{FIELD:} and
		\word{+FIELD}) are defined so they can be used by both
		schools.  Compatibility between the two schools comes from
		defining a new stack item \param{struct-sys}, which is
		implementation dependent and can be 0 or more cells.
		The name first school would provide an address (\param{addr})
297
		as the \param{struct-sys} parameter, while the name last
pknaggs's avatar
pknaggs committed
298 299
		school would defined \param{struct-sys} as being empty.

300 301
		Executing the name of the data structure, returns the size of
		the data structure.  This allows the data stricture to be used
pknaggs's avatar
pknaggs committed
302 303 304
		within another data structure:

		\begin{quote}\ttfamily
305 306 307
		\word{BEGIN-STRUCTURE} point \tab[-0.1] \word{bs} -{}- a-addr 0 ; -{}- lenp \\
		\tab \word{FIELD:} p.x		\tab[5.5] \word{bs} -{}- a-addr cell \\
		\tab \word{FIELD:} p.y      \tab[5.5] \word{bs} -{}- a-addr cell*2 \\
pknaggs's avatar
pknaggs committed
308 309
		\word{END-STRUCTURE} \\

310 311 312
		\word{BEGIN-STRUCTURE} rect  \tab[1.3]\word{bs} -{}- a-addr 0 ; -{}- lenr \\
		\tab point \word{+FIELD} r.tlhc   \tab \word{bs} -{}- a-addr cell*2 \\
		\tab point \word{+FIELD} r.brhc   \tab \word{bs} -{}- a-addr cell*4 \\
pknaggs's avatar
pknaggs committed
313 314 315
		\word{END-STRUCTURE}
		\end{quote}

pknaggs's avatar
pknaggs committed
316
	\item[Alignment] ~\\
pknaggs's avatar
pknaggs committed
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
		In practice, structures are used for two different purposes
		with incompatible requirements:
		\begin{enumerate}
		\item For collecting related internal-use data into a
			convenient ``package'' that can be referred to by a
			single ``handle''. For this use, alignment is important,
			so that efficient native fetch and store instructions
			can be used.

		\item For mapping external data structures like hardware
			register maps and protocol packets. For this use,
			automatic alignment is inappropriate, because the
			alignment of the external data structure often doesn't
			match the rules for a given processor.
		\end{enumerate}

		Many languages cater for the first use, but ignore the
334
		second.  This leads to various customized solutions, usage
pknaggs's avatar
pknaggs committed
335
		requirements, portability problems, bugs, etc.
pknaggs's avatar
pknaggs committed
336
		\word{+FIELD} is defined to be non-a\-lign\-ing, while the
pknaggs's avatar
pknaggs committed
337 338 339
		named field defining words (\emph{x}\texttt{FIELD:}) are
		aligning.  This is intentional and allows for both uses.

340
		The standard currently defines an aligned field defining
pknaggs's avatar
pknaggs committed
341 342 343 344
		word for each of the standard data types:

		\begin{center}
			\begin{tabular}{rl}
pknaggs's avatar
pknaggs committed
345 346
		\word{CFIELD:}					& a character \\
		\word{FIELD:}					& a native integer (single cell) \\
pknaggs's avatar
pknaggs committed
347 348 349 350 351 352 353 354
		\word[floating]{FFIELD:}	& a native float \\
		\word[floating]{SFFIELD:}	& a 32 bit float \\
		\word[floating]{DFFIELD:}	& a 64 bit float
			\end{tabular}
		\end{center}

		Although this is a sufficient set, most systems provide
		facilities to define field defining words for standard
355 356 357
		data types.
		% Note that these also satisfy the alignment requirements of
		% the host system, whereas \word{+FIELD} does not.
pknaggs's avatar
pknaggs committed
358

pknaggs's avatar
pknaggs committed
359
	\item[Future] ~\\
pknaggs's avatar
pknaggs committed
360 361 362 363 364 365 366 367 368 369 370 371
		The following cannot be defined until the required addressing
		has been defined. The names should be considered reserved
		until then.

		\begin{center}
			\begin{tabular}{rl}
			\texttt{BFIELD:} & 1 byte (8 bit) field \\
			\texttt{WFIELD:} & 16 bit field \\
			\texttt{LFIELD:} & 32 bit field \\
			\texttt{XFIELD:} & 64 bit field \\
			\end{tabular}
		\end{center}
pknaggs's avatar
pknaggs committed
372
	\end{rationale}
pknaggs's avatar
pknaggs committed
373

pknaggs's avatar
pknaggs committed
374 375
	\begin{implement} % I.10.6.2.---- BEGIN-STRUCTURE
		\textdf{Begin definition of a new structure. Use in the
pknaggs's avatar
pknaggs committed
376 377 378
		form \word{BEGIN-STRUCTURE} \arg{name}.  At run time
		\arg{name} returns the size of the structure.}

pknaggs's avatar
pknaggs committed
379
		\word{:} \word{BEGIN-STRUCTURE}\tab\word{bs} -{}- addr 0 ; -{}- size \\
pknaggs's avatar
pknaggs committed
380 381
		\tab \word{CREATE} \\
		\tab[2] \word{HERE} 0  0 \word{,} \tab[2] \word{bs}  mark stack, lay dummy \\
382
		\tab \word{DOES} \word{@} \tab[6]\word{bs} -{}- rec-len \\
pknaggs's avatar
pknaggs committed
383
		\word{;}
pknaggs's avatar
pknaggs committed
384
	\end{implement}
pknaggs's avatar
pknaggs committed
385
\end{worddef}
pknaggs's avatar
pknaggs committed
386 387


pknaggs's avatar
pknaggs committed
388
\begin{worddef}{0893}{CFIELD:}[c-field-colon][X:structures]
pknaggs's avatar
pknaggs committed
389
\item \stack{n_1 "<spaces>name"}{n_2}
pknaggs's avatar
pknaggs committed
390

pknaggs's avatar
pknaggs committed
391 392 393 394
	Skip leading space delimiters. Parse \param{name} delimited by
	a space. \param{Offset} is the first character aligned value
	greater than or equal to \param{n_1}.  \param{n_2 = offset + 1}
	character.
pknaggs's avatar
pknaggs committed
395

pknaggs's avatar
pknaggs committed
396 397
	Create a definition for \param{name} with the execution semantics
	given below.
pknaggs's avatar
pknaggs committed
398

pknaggs's avatar
pknaggs committed
399
\execute[name]
pknaggs's avatar
pknaggs committed
400
	\stack{addr_1}{addr_2}
pknaggs's avatar
pknaggs committed
401

pknaggs's avatar
pknaggs committed
402
	Add the \param{offset} calculated during the compile-time action to
403
	\param{addr_1} giving the address \param{addr_2}.
pknaggs's avatar
pknaggs committed
404

pknaggs's avatar
pknaggs committed
405
\see \wref{facility:+FIELD}{+FIELD},
pknaggs's avatar
pknaggs committed
406 407
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\
	\wref{facility:END-STRUCTURE}{END-STRUCTURE},
pknaggs's avatar
pknaggs committed
408 409
	\rref{facility:FIELD:}{}.
\end{worddef}
pknaggs's avatar
pknaggs committed
410 411 412

% -------------------------------------

413
\begin{worddef}{1305}{EKEY}[e-key]
pknaggs's avatar
pknaggs committed
414
\item \stack{}{x}
415

pknaggs's avatar
pknaggs committed
416
	Receive one keyboard event \param{x}. The encoding of keyboard events
417 418
	is implementation defined.

pknaggs's avatar
pknaggs committed
419 420 421
\see \wref{core:KEY}{KEY},
	\wref{facility:KEYq}{KEY?},
	\rref{facility:EKEY}{}.
422

423

pknaggs's avatar
pknaggs committed
424
	\begin{rationale} % A.10.6.2.1305 EKEY
425 426 427
		For some input devices, such as keyboards, more information is
		available than can be returned by a single execution of
		\word{KEY}.  \word{EKEY} provides a standard word to access a
pknaggs's avatar
pknaggs committed
428
		system-dependent set of events.
429 430 431 432 433 434

		\word{EKEY} and \word{EKEYq} are implementation specific; no
		assumption can be made regarding the interaction between the
		pairs \word{EKEY}/\word{EKEYq} and \word{KEY}/\word{KEYq}.
		This standard does not define a timing relationship between
		\word{KEYq} and \word{EKEYq}.  Undefined results may be
pknaggs's avatar
pknaggs committed
435
		avoided by using only one pairing of \word{KEY}/ \word{KEYq}
436
		or \word{EKEY}/\word{EKEYq} in a program for each input
pknaggs's avatar
pknaggs committed
437
		stream.
438 439 440 441 442 443 444 445

		\word{EKEY} assumes no particular numerical correspondence
		between particular event code values and the values
		representing standard characters.  On some systems, this may
		allow two separate keys that correspond to the same standard
		character to be distinguished from one another.  A standard
		program may only interpret the results of \word{EKEY} via the
		translation words provided for that purpose
pknaggs's avatar
pknaggs committed
446
		(\word{EKEYtoCHAR} and \word{EKEYtoFKEY}).
447 448

		See: \rref{core:KEY}{}, \wref{facility:EKEYtoCHAR}{} and
pknaggs's avatar
pknaggs committed
449
		\wref{facility:EKEYtoFKEY}{}.
pknaggs's avatar
pknaggs committed
450
	\end{rationale}
451 452 453 454
\end{worddef}


\begin{worddef}[EKEYtoCHAR]{1306}{EKEY>CHAR}[e-key-to-char]
pknaggs's avatar
pknaggs committed
455
\item \stack{x}{x false | char true}
456

pknaggs's avatar
pknaggs committed
457
	If the keyboard event \param{x} corresponds to a character in the
458
	implementation-defined character set, return that character and
pknaggs's avatar
pknaggs committed
459
	\emph{true}. Otherwise return \param{x} and \emph{false}.
460

pknaggs's avatar
pknaggs committed
461
\see \rref{facility:EKEYtoCHAR}{}.
462

pknaggs's avatar
pknaggs committed
463
	\begin{rationale} % A.10.6.2.1306 EKEY>CHAR
464 465 466 467 468 469 470
		\word{EKEYtoCHAR} translates a keyboard event into the
		corresponding member of the character set, if such a
		correspondence exists for that event.

		It is possible that several different keyboard events may
		correspond to the same character, and other keyboard events
		may correspond to no character.
pknaggs's avatar
pknaggs committed
471
	\end{rationale}
472 473 474 475 476
\end{worddef}


% -------------------------------------------------------------------

pknaggs's avatar
pknaggs committed
477
\begin{worddef}[EKEYtoFKEY]{1306}[40]{EKEY>FKEY}[e-key-to-f-key][X:ekeys]
pknaggs's avatar
pknaggs committed
478
\item \stack{x}{u flag}
479

pknaggs's avatar
pknaggs committed
480
	If the keyboard event \param{x} corresponds to a keypress in the
481
	implementation-defined special key set, return that key's id
pknaggs's avatar
pknaggs committed
482
	\param{u} and \param{true}. Otherwise return \param{x} and
483 484
	\param{false}.

pknaggs's avatar
pknaggs committed
485
\note
486 487 488
	The keyboard may lack some of the keys, or the capability to report
	them. Programs should be written such that they also work (although
	less conveniently or with less functionality) if these key numbers
pknaggs's avatar
pknaggs committed
489
	cannot be produced.
490

pknaggs's avatar
pknaggs committed
491 492 493 494
\see
	\wref{facility:EKEY}{EKEY},
	\wref{facility:K-ALT-MASK}{K-ALT-MASK},
	\wref{facility:K-CTRL-MASK}{K-CTRL-MASK}, \linebreak
495 496
	\wref{facility:K-DELETE}{K-DELETE},
	\wref{facility:K-DOWN}{K-DOWN},
pknaggs's avatar
pknaggs committed
497
	\wref{facility:K-END}{K-END}, \linebreak
498
	\wref{facility:K-F1}{K-F1},
pknaggs's avatar
pknaggs committed
499 500 501 502 503
	\wref{facility:K-F10}{K-F10},
	\wref{facility:K-F11}{K-F11}, \linebreak
	\wref{facility:K-F12}{K-F12},
	\wref{facility:K-F2}{K-F2},
	\wref{facility:K-F3}{K-F3}, \linebreak
504 505
	\wref{facility:K-F4}{K-F4},
	\wref{facility:K-F5}{K-F5},
pknaggs's avatar
pknaggs committed
506 507
	\wref{facility:K-F6}{K-F6}, \linebreak
	\wref{facility:K-F7}{K-F7},
508
	\wref{facility:K-F8}{K-F8},
pknaggs's avatar
pknaggs committed
509 510 511 512 513 514 515 516 517
	\wref{facility:K-F9}{K-F9}, \linebreak
	\wref{facility:K-HOME}{K-HOME},
	\wref{facility:K-INSERT}{K-INSERT},
	\wref{facility:K-LEFT}{K-LEFT}, \linebreak
	\wref{facility:K-NEXT}{K-NEXT},
	\wref{facility:K-PRIOR}{K-PRIOR},
	\wref{facility:K-RIGHT}{K-RIGHT}, \linebreak
	\wref{facility:K-SHIFT-MASK}{K-SHIFT-MASK},
	\wref{facility:K-UP}{K-UP}, \linebreak
pknaggs's avatar
pknaggs committed
518
	\rref{facility:EKEYtoFKEY}{}.
519

520

pknaggs's avatar
pknaggs committed
521
	\begin{rationale} % A.10.6.2.---- EKEY>FKEY
522 523


524 525 526 527 528 529 530
		\word{EKEY} produces an abstract cell type for a keyboard
		event (e.g., a keyboard scan code).  \word{EKEYtoFKEY} checks
		if such an event corresponds to a special (non-graphic) key
		press, and if so, returns a code for the special key press.
		The encoding of special keys (returned by \word{EKEYtoFKEY})
		may be different from the encoding of these keys as keyboard
		events (input to \word{EKEYtoFKEY}).
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548

		Typical Use:

		\begin{quote}
			{\ldots} \word{EKEY} \word{EKEYtoFKEY} \word{IF} \\
			\tab \word{CASE} \\
			\tab[2] \word{K-UP} \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] \word{K-F1} \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] \word{K-LEFT} \word{K-SHIFT-MASK} \word{OR}
			                      \word{K-CTRL-MASK} \word{OR}
			                    \word{OF} {\ldots} \word{ENDOF} \\
			\tab[2] {\ldots} \\
			\tab \word{ENDCASE} \\
			\word{ELSE} \\
			\tab {\ldots} \\
			\word{THEN}
		\end{quote}

pknaggs's avatar
pknaggs committed
549 550
		The codes for the special keys are system-dependent, but this
		standard provides words for getting the key codes for a number
551
		of keys:
pknaggs's avatar
pknaggs committed
552 553

	\begin{center}
554
		\begin{tabular}{llcll}
pknaggs's avatar
pknaggs committed
555
		\hline
556 557 558 559 560 561 562 563 564 565 566 567 568
		Word & Key & \hspace{2em} & Word & Key \\ \hline\hline
		\word{K-F1}		& F1	& & \word{K-LEFT}	& cursor left	\\
		\word{K-F2}		& F2	& & \word{K-RIGHT}	& cursor right	\\
		\word{K-F3}		& F3	& & \word{K-UP}		& cursor up		\\
		\word{K-F4}		& F4	& & \word{K-DOWN}	& cursor down	\\
		\word{K-F5}		& F5	& & \word{K-HOME}	& home or Pos1	\\
		\word{K-F6}		& F6	& & \word{K-END}	& End			\\
		\word{K-F7}		& F7	& & \word{K-PRIOR}	& PgUp or Prior	\\
		\word{K-F8}		& F8	& & \word{K-NEXT}	& PgDn or Next	\\
		\word{K-F9}		& F9	& & \word{K-INSERT}	& Insert		\\
		\word{K-F10}	& F10	& & \word{K-DELETE}	& Delete		\\
		\word{K-F11}	& F11	\\
		\word{K-F12}	& F12	\\ \hline
pknaggs's avatar
pknaggs committed
569 570 571
		\end{tabular}
	\end{center}

572 573
		In addition, you can get codes for shifted variants of these
		keys by \word{OR}ing with \word{K-SHIFT-MASK}, \word{K-CTRL-MASK}
pknaggs's avatar
pknaggs committed
574 575 576 577 578 579 580
		and/or \word{K-ALT-MASK}, e.g. \word{K-CTRL-MASK}
		\word{K-ALT-MASK} \word{OR} \word{K-DELETE} \word{OR}.
		The masks for the shift keys are:

	\begin{center}
		\begin{tabular}{ll}
		\hline
581 582 583 584
		Word 				& Key	\\ \hline\hline
		\word{K-SHIFT-MASK}	& Shift	\\
		\word{K-CTRL-MASK}	& Ctrl	\\
		\word{K-ALT-MASK}	& Alt	\\ \hline
pknaggs's avatar
pknaggs committed
585 586 587 588 589 590 591
		\end{tabular}
	\end{center}

		Note that not all of these keys are available on all systems, and not
		all combinations of keys and shift keys are available.  Therefore
		programs should be written such that they continue to work (although
		less conveniently or with less functionality) if these key combinations
592
		cannot be produced.
pknaggs's avatar
pknaggs committed
593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632
	\end{rationale}

	\begin{implement} % I.10.6.2.--- EKEY>FKEY
		\textdf{The implementation is closely tied to the implementation
			of \word{EKEY} and therefore unportable.}
	\end{implement}

	\begin{testing} % T.10.6.2.---- EKEY>FKEY
		\ttfamily
		\word{:} TFKEY" \word{p} "ccc<quote>" -{}- u flag ) \\
		\tab[1.2] \word{CR} \word{.q} Please press " \word{POSTPONE} \word[file]{.q} \word{EKEY} \word{EKEYtoFKEY} \word{;}

		\test{TFKEY" <left>" }{\word{K-LEFT}  <TRUE>} \\
		\test{TFKEY" <right>"}{\word{K-RIGHT} <TRUE>} \\
		\test{TFKEY" <up>"   }{\word{K-UP}    <TRUE>} \\
		\test{TFKEY" <down>" }{\word{K-DOWN}  <TRUE>} \\
		\test{TFKEY" <home>" }{\word{K-HOME}  <TRUE>} \\
		\test{TFKEY" <end>"  }{\word{K-END}   <TRUE>} \\
		\test{TFKEY" <prior>"}{\word{K-PRIOR} <TRUE>} \\
		\test{TFKEY" <next>" }{\word{K-NEXT}  <TRUE>}

		\test{TFKEY" <F1>" }{\word{K-F1}  <TRUE>} \\
		\test{TFKEY" <F2>" }{\word{K-F2}  <TRUE>} \\
		\test{TFKEY" <F3>" }{\word{K-F3}  <TRUE>} \\
		\test{TFKEY" <F4>" }{\word{K-F4}  <TRUE>} \\
		\test{TFKEY" <F5>" }{\word{K-F5}  <TRUE>} \\
		\test{TFKEY" <F6>" }{\word{K-F6}  <TRUE>} \\
		\test{TFKEY" <F7>" }{\word{K-F7}  <TRUE>} \\
		\test{TFKEY" <F8>" }{\word{K-F8}  <TRUE>} \\
		\test{TFKEY" <F9>" }{\word{K-F9}  <TRUE>} \\
		\test{TFKEY" <F10>"}{\word{K-F10} <TRUE>} \\
		\test{TFKEY" <F11>"}{\word{K-F11} <TRUE>} \\
		\test{TFKEY" <F11>"}{\word{K-F12} <TRUE>}

		\test{TFKEY" <shift-left>"}{\word{K-LEFT} \word{K-SHIFT-MASK} \word{OR} <TRUE>} \\
		\test{TFKEY" <ctrl-left>" }{\word{K-LEFT} \word{K-CTRL-MASK}  \word{OR} <TRUE>} \\
		\test{TFKEY" <alt-left>"  }{\word{K-LEFT} \word{K-ALT-MASK}   \word{OR} <TRUE>}

		\test{TFKEY" <a>" \word{SWAP} \word{EKEYtoCHAR}}{<FALSE> CHAR a <TRUE>} \\
	\end{testing}
pknaggs's avatar
pknaggs committed
633
\end{worddef}
634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659


% -------------------------------------------------------------------

\begin{worddef}[EKEYq]{1307}{EKEY?}[e-key-question]
\item \stack{}{flag}

	If a keyboard event is available, return \emph{true}. Otherwise
	return \emph{false}. The event shall be returned by the next
	execution of \word{EKEY}.

	After \word{EKEYq} returns with a value of \emph{true},
	subsequent executions of \word{EKEYq} prior to the execution of
	\word[core]{KEY}, \word{KEYq} or \word{EKEY} also return
	\emph{true}, referring to the same event.
\end{worddef}


\begin{worddef}[EMITq]{1325}{EMIT?}[emit-question]
\item \stack{}{flag}

	\param{flag} is true if the user output device is ready to
	accept data and the execution of \word[core]{EMIT} in place of
	\word{EMITq} would not have suffered an indefinite delay. If
	the device status is indeterminate, \emph{flag} is true.

pknaggs's avatar
pknaggs committed
660
\see \rref{facility:EMITq}{}.
661

pknaggs's avatar
pknaggs committed
662
	\begin{rationale} % A.10.6.2.1325 EMIT?
663 664 665
		An indefinite delay is a device related condition, such as
		printer off-line, that requires operator intervention before
		the device will accept new data.
pknaggs's avatar
pknaggs committed
666
	\end{rationale}
667 668
\end{worddef}

pknaggs's avatar
pknaggs committed
669
% -------------------------------------
pknaggs's avatar
pknaggs committed
670
\begin{worddef}{1336}{END-STRUCTURE}[][X:structures]
pknaggs's avatar
pknaggs committed
671 672 673 674 675
\item \stack{struct-sys +n}{}

	Terminate definition of a structure started by
	\word{BEGIN-STRUCTURE}.

pknaggs's avatar
pknaggs committed
676
\see \wref{facility:+FIELD}{+FIELD},
pknaggs's avatar
pknaggs committed
677 678
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}.

pknaggs's avatar
pknaggs committed
679 680
	\begin{implement} % I.10.6.2.---- END-STRUCTURE
		\textdf{Terminate definition of a structure.}
pknaggs's avatar
pknaggs committed
681

pknaggs's avatar
pknaggs committed
682
		\word{:} \word{END-STRUCTURE}\tab\word{bs} addr n -{}- \\
pknaggs's avatar
pknaggs committed
683
		\tab \word{SWAP} \word{!} \word{;} \tab[4.2]\word{bs} set len
pknaggs's avatar
pknaggs committed
684
	\end{implement}
pknaggs's avatar
pknaggs committed
685
\end{worddef}
pknaggs's avatar
pknaggs committed
686

pknaggs's avatar
pknaggs committed
687
\newpage
pknaggs's avatar
pknaggs committed
688
\begin{worddef}{1518}{FIELD:}[field-colon][X:structures]
pknaggs's avatar
pknaggs committed
689
\item \stack{n_1 "<spaces>name"}{n_2}
pknaggs's avatar
pknaggs committed
690

pknaggs's avatar
pknaggs committed
691
	Skip leading space delimiters. Parse \param{name} delimited by
pknaggs's avatar
pknaggs committed
692
	a space. \param{Offset} is the first cell aligned value greater
pknaggs's avatar
pknaggs committed
693
	than or equal to \param{n_1}.  \param{n_2 = offset + 1} cell.
pknaggs's avatar
pknaggs committed
694

pknaggs's avatar
pknaggs committed
695 696
	Create a definition for \param{name} with the execution semantics
	given below.
pknaggs's avatar
pknaggs committed
697

pknaggs's avatar
pknaggs committed
698
\execute[name]
pknaggs's avatar
pknaggs committed
699
	\stack{addr_1}{addr_2}
pknaggs's avatar
pknaggs committed
700

pknaggs's avatar
pknaggs committed
701
	Add the \param{offset} calculated during the compile-time action
702
	to \param{addr_1} giving the address \param{addr_2}.
pknaggs's avatar
pknaggs committed
703

pknaggs's avatar
pknaggs committed
704
\see \wref{facility:+FIELD}{+FIELD},
pknaggs's avatar
pknaggs committed
705 706
	\wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\
	\wref{facility:END-STRUCTURE}{END-STRUCTURE},
pknaggs's avatar
pknaggs committed
707
	\rref{facility:FIELD:}{}.
pknaggs's avatar
pknaggs committed
708 709

	\begin{rationale}
pknaggs's avatar
pknaggs committed
710
		Create an aligned single-cell field in a data structure.
pknaggs's avatar
pknaggs committed
711

pknaggs's avatar
pknaggs committed
712 713
		The various \emph{x}\texttt{FIELD:} words provide for different
		alignment and size allocation.
pknaggs's avatar
pknaggs committed
714

pknaggs's avatar
pknaggs committed
715
		The \emph{x}\texttt{FIELD:} words could be defined as:
pknaggs's avatar
pknaggs committed
716 717

		\begin{tabbing}
pknaggs's avatar
pknaggs committed
718
			\tab \= \tab[6] \= \tab[22] \= \tab[5] \= \tab[5.2] \= \kill
pknaggs's avatar
pknaggs committed
719 720
			\> \word{:} \word{FIELD:}   \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{ALIGNED}   \' 1 \word{CELLS}   \> \word{+FIELD} \word{;} \\
			\> \word{:} \word{CFIELD:}  \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\>                  \' 1 \word{CHARS}   \> \word{+FIELD} \word{;} \\
pknaggs's avatar
pknaggs committed
721
		\setwordlist{floating}
pknaggs's avatar
pknaggs committed
722 723 724
			\> \word{:} \word{FFIELD:}  \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{FALIGNED}  \' 1 \word{FLOATS}  \> \word[facility]{+FIELD} \word{;} \\
			\> \word{:} \word{SFFIELD:} \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{SFALIGNED} \' 1 \word{SFLOATS} \> \word[facility]{+FIELD} \word{;} \\
			\> \word{:} \word{DFFIELD:} \>( n1 "name" -{}- n2 ; addr1 -{}- addr2 )\> \word{DFALIGNED} \' 1 \word{DFLOATS} \> \word[facility]{+FIELD} \word{;}
pknaggs's avatar
pknaggs committed
725 726 727
		\setwordlist{facility}
		\end{tabbing}
	\end{rationale}
pknaggs's avatar
pknaggs committed
728
\end{worddef}
729

pknaggs's avatar
pknaggs committed
730
% -------------------------------------------------------------------
731

pknaggs's avatar
pknaggs committed
732
\begin{worddef}{1740}[01]{K-ALT-MASK}[][X:ekeys]
733 734 735 736 737 738 739 740 741
\item \stack{}{u}

	Mask for the \textsc{Alt} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
742
\end{worddef}
743 744


pknaggs's avatar
pknaggs committed
745
\begin{worddef}{1740}[02]{K-CTRL-MASK}[][X:ekeys]
746 747 748 749 750 751 752 753 754
\item \stack{}{u}

	Mask for the \textsc{Ctrl} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
755
\end{worddef}
756 757


pknaggs's avatar
pknaggs committed
758
\begin{worddef}{1740}[03]{K-DELETE}[][X:ekeys]
759 760 761 762 763 764 765 766
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``Delete'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
767
\end{worddef}
768 769


pknaggs's avatar
pknaggs committed
770
\begin{worddef}{1740}[04]{K-DOWN}[][X:ekeys]
771 772 773 774 775 776 777 778
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor down'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
779
\end{worddef}
780 781


pknaggs's avatar
pknaggs committed
782
\begin{worddef}{1740}[05]{K-END}[][X:ekeys]
783 784 785 786 787 788 789 790
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``End'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
791
\end{worddef}
792 793


pknaggs's avatar
pknaggs committed
794
\begin{worddef}{1740}[06]{K-F1}[k-f-1][X:ekeys]
795 796 797 798 799 800 801 802
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F1'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
803
\end{worddef}
804 805


pknaggs's avatar
pknaggs committed
806
\begin{worddef}{1740}[07]{K-F10}[k-f-10][X:ekeys]
807 808 809 810 811 812 813 814
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F10'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
815
\end{worddef}
816 817


pknaggs's avatar
pknaggs committed
818
\begin{worddef}{1740}[08]{K-F11}[k-f-11][X:ekeys]
819 820 821 822 823 824 825 826
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F11'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
827
\end{worddef}
828 829


pknaggs's avatar
pknaggs committed
830
\begin{worddef}{1740}[09]{K-F12}[k-f-12][X:ekeys]
831 832 833 834 835 836 837 838
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F12'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
839
\end{worddef}
840 841


pknaggs's avatar
pknaggs committed
842
\begin{worddef}{1740}[10]{K-F2}[k-f-2][X:ekeys]
843 844 845 846 847 848 849 850
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F2'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
851
\end{worddef}
852 853


pknaggs's avatar
pknaggs committed
854
\begin{worddef}{1740}[11]{K-F3}[k-f-3][X:ekeys]
855 856 857 858 859 860 861 862
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F3'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
863
\end{worddef}
864 865


pknaggs's avatar
pknaggs committed
866
\begin{worddef}{1740}[12]{K-F4}[k-f-4][X:ekeys]
867 868 869 870 871 872 873 874
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F4'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
875
\end{worddef}
876 877


pknaggs's avatar
pknaggs committed
878
\begin{worddef}{1740}[13]{K-F5}[k-f-5][X:ekeys]
879 880 881 882 883 884 885 886
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F5'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
887
\end{worddef}
888 889


pknaggs's avatar
pknaggs committed
890
\begin{worddef}{1740}[14]{K-F6}[k-f-6][X:ekeys]
891 892 893 894 895 896 897 898
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F6'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
899
\end{worddef}
900 901


pknaggs's avatar
pknaggs committed
902
\begin{worddef}{1740}[15]{K-F7}[k-f-7][X:ekeys]
903 904 905 906 907 908 909 910
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F7'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
911
\end{worddef}
912 913


pknaggs's avatar
pknaggs committed
914
\begin{worddef}{1740}[16]{K-F8}[k-f-8][X:ekeys]
915 916 917 918 919 920 921 922
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F8'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
923
\end{worddef}
924 925


pknaggs's avatar
pknaggs committed
926
\begin{worddef}{1740}[17]{K-F9}[k-f-9][X:ekeys]
927 928 929 930 931 932 933 934
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``F9'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
935
\end{worddef}
936 937


pknaggs's avatar
pknaggs committed
938
\begin{worddef}{1740}[18]{K-HOME}[][X:ekeys]
939 940 941 942 943 944 945 946
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``home'' or ``Pos1'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
947
\end{worddef}
948 949


pknaggs's avatar
pknaggs committed
950
\begin{worddef}{1740}[19]{K-INSERT}[][X:ekeys]
951 952 953 954 955 956 957 958
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``Insert'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
959
\end{worddef}
960 961


pknaggs's avatar
pknaggs committed
962
\begin{worddef}{1740}[20]{K-LEFT}[][X:ekeys]
963 964 965 966 967 968 969 970
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor left'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
971
\end{worddef}
972 973


pknaggs's avatar
pknaggs committed
974
\begin{worddef}{1740}[21]{K-NEXT}[][X:ekeys]
975 976 977 978 979 980 981 982
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``PgDn'' (Page Down) or ``Next'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
983
\end{worddef}
984 985


pknaggs's avatar
pknaggs committed
986
\begin{worddef}{1740}[22]{K-PRIOR}[][X:ekeys]
987 988 989 990 991 992 993 994
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``PgUp'' (Page Up) or ``Prior'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
995
\end{worddef}
996 997


pknaggs's avatar
pknaggs committed
998
\begin{worddef}{1740}[23]{K-RIGHT}[][X:ekeys]
999 1000 1001 1002 1003 1004 1005 1006
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor right'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
1007
\end{worddef}
1008 1009


pknaggs's avatar
pknaggs committed
1010
\begin{worddef}{1740}[24]{K-SHIFT-MASK}[][X:ekeys]
1011 1012 1013 1014 1015 1016 1017 1018 1019
\item \stack{}{u}

	Mask for the \textsc{Shift} key, that can be \word{OR}ed with the
	key value to produce a value that the sequence \word{EKEY}
	\word{EKEYtoFKEY} may produce when the user presses the
	corresponding key combination.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
1020
\end{worddef}
1021 1022


pknaggs's avatar
pknaggs committed
1023
\begin{worddef}{1740}[25]{K-UP}[][X:ekeys]
1024 1025 1026 1027 1028 1029 1030 1031
\item \stack{}{u}

	Leaves the value \param{u} that the sequence \word{EKEY}
	\word{EKEYtoFKEY} would produce when the user presses the
	``cursor up'' key.

\see \wref{facility:EKEYtoFKEY}{EKEY>FKEY},
	\rref{facility:EKEYtoFKEY}{EKEY>FKEY}.
pknaggs's avatar
pknaggs committed
1032
\end{worddef}
1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044


% -------------------------------------------------------------------


\begin{worddef}{1905}{MS}
\item \stack{u}{}

	Wait at least \param{u} milliseconds.

\note
	The actual length and variability of the time period depends
pknaggs's avatar
pknaggs committed
1045
	upon the {im\-ple\-ment\-ation-de\-fin\-ed} resolution of the system clock
1046
	and upon other system and computer characteristics beyond the
pknaggs's avatar
pknaggs committed
1047
	scope of this standard.
1048

pknaggs's avatar
pknaggs committed
1049
\see \rref{facility:MS}{}.
1050

pknaggs's avatar
pknaggs committed
1051
	\begin{rationale} % A.10.6.2.1905 MS
1052 1053 1054 1055 1056 1057
		Although their frequencies vary, every system has a clock.
		Since many programs need to time intervals, this word is
		offered. Use of milliseconds as an internal unit of time is
		a practical ``least common denominator'' external unit. It
		is assumed implementors will use ``clock ticks'' (whatever
		size they are) as an internal unit and convert as appropriate.
pknaggs's avatar
pknaggs committed
1058
	\end{rationale}
1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069
\end{worddef}


\begin{worddef}[TIMEandDATE]{2292}{TIME\&DATE}[time-and-date]
\item \stack{}{+n_1 +n_2 +n_3 +n_4 +n_5 +n_6}

	Return the current time and date.
	\param{+n_1} is the second \{0{\ldots}59\},
	\param{+n_2} is the minute \{0{\ldots}59\},
	\param{+n_3} is the hour \{0{\ldots}23\},
	\param{+n_4} is the day \{1{\ldots}31\},
pknaggs's avatar
pknaggs committed
1070
	\param{+n_5} is the month \{1{\ldots}12\} and
1071 1072
	\param{+n_6} is the year (e.g., 1991).

pknaggs's avatar
pknaggs committed
1073
\see \rref{facility:TIMEandDATE}{}.
1074

pknaggs's avatar
pknaggs committed
1075
	\begin{rationale} % A.10.6.2.2292 TIME&DATE
1076 1077
		Most systems have a real-time clock/calendar.
		This word gives portable access to it.
pknaggs's avatar
pknaggs committed
1078
	\end{rationale}
1079
\end{worddef}