% !TeX root = forth.tex \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 \subsection{Data types} % 10.3.1 Append table \ref{facility:types} to table \ref{table:datatypes}. \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 \emph{struct-sys} & data structures & implementation dependent \\ \hline\hline \end{tabular} \end{center} \end{table} \subsubsection{Structure type} % 10.3.1.1 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} throughout this standard. \subsubsection{Character types} % 10.3.1.2 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 user output device; \item A \param{name} defined by \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE} is executed before the corresponding \linebreak \wref{facility:END-STRUCTURE}{END-STRUCTURE} has been executed. \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 \subsection{Forth-\snapshot{} systems} % 10.5.1 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. \subsection{Forth-\snapshot{} programs} % 10.5.2 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. \see \rref{facility:KEYq}{}. \begin{rationale} % A.10.6.1.1755 KEY? The committee has gone around several times on the 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 application does not wish to process non-character events, 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. \end{rationale} \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 % ------------------------------------- \begin{worddef}{0135}{+FIELD}[plus-field][X:structures] \item \stack{n_1 n_2 "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}, \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\ \wref{facility:CFIELD:}{CFIELD:}, \wref{facility:FIELD:}{FIELD:}, \wref{floating:FFIELD:}{FFIELD:}, \\ \wref{floating:SFFIELD:}{SFFIELD:}, \wref{floating:DFFIELD:}{DFFIELD:}, \rref{facility:+FIELD}{}. \begin{rationale} % A.10.6.2.---- +FIELD \word{+FIELD} is not required to align items. This is deliberate and allows the construction of unaligned data 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. \end{rationale} \begin{implement} % I.10.6.2.---- +FIELD \textdf{Create a new field within a structure definition of size \param{n} bytes.} \word{:} +FIELD\tab\word{bs} n <"name"> -{}- ; Exec: addr -{}- 'addr \\ \tab \word{CREATE} \word{OVER} \word{,} \word{+} \\ \tab \word{DOES} \word{@} \word{+} \\ \word{;} \end{implement} \end{worddef} \begin{worddef}{0763}{BEGIN-STRUCTURE}[][X:structures] \item \stack{"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. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \\ \rref{facility:BEGIN-STRUCTURE}{}. \begin{rationale} % A.10.6.2.---- BEGIN-STRUCTURE There are two schools of thought regarding named data 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 \\ \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 \end{quote} While the name first school would define the same data structure as: \begin{quote}\ttfamily \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 \\ \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}) as the \param{struct-sys} parameter, while the name last school would defined \param{struct-sys} as being empty. Executing the name of the data structure, returns the size of the data structure. This allows the data stricture to be used within another data structure: \begin{quote}\ttfamily \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 \\ \word{END-STRUCTURE} \\ \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 \\ \word{END-STRUCTURE} \end{quote} \item[Alignment] ~\\ 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 second. This leads to various customized solutions, usage requirements, portability problems, bugs, etc. \word{+FIELD} is defined to be non-a\-lign\-ing, while the named field defining words (\emph{x}\texttt{FIELD:}) are aligning. This is intentional and allows for both uses. The standard currently defines an aligned field defining word for each of the standard data types: \begin{center} \begin{tabular}{rl} \word{CFIELD:} & a character \\ \word{FIELD:} & a native integer (single cell) \\ \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 data types. % Note that these also satisfy the alignment requirements of % the host system, whereas \word{+FIELD} does not. \item[Future] ~\\ 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} \end{rationale} \begin{implement} % I.10.6.2.---- BEGIN-STRUCTURE \textdf{Begin definition of a new structure. Use in the form \word{BEGIN-STRUCTURE} \arg{name}. At run time \arg{name} returns the size of the structure.} \word{:} \word{BEGIN-STRUCTURE}\tab\word{bs} -{}- addr 0 ; -{}- size \\ \tab \word{CREATE} \\ \tab[2] \word{HERE} 0 0 \word{,} \tab[2] \word{bs} mark stack, lay dummy \\ \tab \word{DOES} \word{@} \tab[6]\word{bs} -{}- rec-len \\ \word{;} \end{implement} \end{worddef} \begin{worddef}{0893}{CFIELD:}[c-field-colon][X:structures] \item \stack{n_1 "name"}{n_2} 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. Create a definition for \param{name} with the execution semantics given below. \execute[name] \stack{addr_1}{addr_2} Add the \param{offset} calculated during the compile-time action to \param{addr_1} giving the address \param{addr_2}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\ \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \rref{facility:FIELD:}{}. \end{worddef} % ------------------------------------- \begin{worddef}{1305}{EKEY}[e-key] \item \stack{}{x} Receive one keyboard event \param{x}. The encoding of keyboard events is implementation defined. \see \wref{core:KEY}{KEY}, \wref{facility:KEYq}{KEY?}, \rref{facility:EKEY}{}. \begin{rationale} % A.10.6.2.1305 EKEY 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 system-dependent set of events. \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 avoided by using only one pairing of \word{KEY}/ \word{KEYq} or \word{EKEY}/\word{EKEYq} in a program for each input stream. \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 (\word{EKEYtoCHAR} and \word{EKEYtoFKEY}). See: \rref{core:KEY}{}, \wref{facility:EKEYtoCHAR}{} and \wref{facility:EKEYtoFKEY}{}. \end{rationale} \end{worddef} \begin{worddef}[EKEYtoCHAR]{1306}{EKEY>CHAR}[e-key-to-char] \item \stack{x}{x false | char true} If the keyboard event \param{x} corresponds to a character in the implementation-defined character set, return that character and \emph{true}. Otherwise return \param{x} and \emph{false}. \see \rref{facility:EKEYtoCHAR}{}. \begin{rationale} % A.10.6.2.1306 EKEY>CHAR \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. \end{rationale} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}[EKEYtoFKEY]{1306}[40]{EKEY>FKEY}[e-key-to-f-key][X:ekeys] \item \stack{x}{u flag} If the keyboard event \param{x} corresponds to a keypress in the implementation-defined special key set, return that key's id \param{u} and \param{true}. Otherwise return \param{x} and \param{false}. \note 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 cannot be produced. \see \wref{facility:EKEY}{EKEY}, \wref{facility:K-ALT-MASK}{K-ALT-MASK}, \wref{facility:K-CTRL-MASK}{K-CTRL-MASK}, \linebreak \wref{facility:K-DELETE}{K-DELETE}, \wref{facility:K-DOWN}{K-DOWN}, \wref{facility:K-END}{K-END}, \linebreak \wref{facility:K-F1}{K-F1}, \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 \wref{facility:K-F4}{K-F4}, \wref{facility:K-F5}{K-F5}, \wref{facility:K-F6}{K-F6}, \linebreak \wref{facility:K-F7}{K-F7}, \wref{facility:K-F8}{K-F8}, \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 \rref{facility:EKEYtoFKEY}{}. \begin{rationale} % A.10.6.2.---- EKEY>FKEY \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}). 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} The codes for the special keys are system-dependent, but this standard provides words for getting the key codes for a number of keys: \begin{center} \begin{tabular}{llcll} \hline 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 \end{tabular} \end{center} 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} 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 Word & Key \\ \hline\hline \word{K-SHIFT-MASK} & Shift \\ \word{K-CTRL-MASK} & Ctrl \\ \word{K-ALT-MASK} & Alt \\ \hline \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 cannot be produced. \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" -{}- u flag ) \\ \tab[1.2] \word{CR} \word{.q} Please press " \word{POSTPONE} \word[file]{.q} \word{EKEY} \word{EKEYtoFKEY} \word{;} \test{TFKEY" " }{\word{K-LEFT} } \\ \test{TFKEY" "}{\word{K-RIGHT} } \\ \test{TFKEY" " }{\word{K-UP} } \\ \test{TFKEY" " }{\word{K-DOWN} } \\ \test{TFKEY" " }{\word{K-HOME} } \\ \test{TFKEY" " }{\word{K-END} } \\ \test{TFKEY" "}{\word{K-PRIOR} } \\ \test{TFKEY" " }{\word{K-NEXT} } \test{TFKEY" " }{\word{K-F1} } \\ \test{TFKEY" " }{\word{K-F2} } \\ \test{TFKEY" " }{\word{K-F3} } \\ \test{TFKEY" " }{\word{K-F4} } \\ \test{TFKEY" " }{\word{K-F5} } \\ \test{TFKEY" " }{\word{K-F6} } \\ \test{TFKEY" " }{\word{K-F7} } \\ \test{TFKEY" " }{\word{K-F8} } \\ \test{TFKEY" " }{\word{K-F9} } \\ \test{TFKEY" "}{\word{K-F10} } \\ \test{TFKEY" "}{\word{K-F11} } \\ \test{TFKEY" "}{\word{K-F12} } \test{TFKEY" "}{\word{K-LEFT} \word{K-SHIFT-MASK} \word{OR} } \\ \test{TFKEY" " }{\word{K-LEFT} \word{K-CTRL-MASK} \word{OR} } \\ \test{TFKEY" " }{\word{K-LEFT} \word{K-ALT-MASK} \word{OR} } \test{TFKEY" " \word{SWAP} \word{EKEYtoCHAR}}{ CHAR a } \\ \end{testing} \end{worddef} % ------------------------------------------------------------------- \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. \see \rref{facility:EMITq}{}. \begin{rationale} % A.10.6.2.1325 EMIT? An indefinite delay is a device related condition, such as printer off-line, that requires operator intervention before the device will accept new data. \end{rationale} \end{worddef} % ------------------------------------- \begin{worddef}{1336}{END-STRUCTURE}[][X:structures] \item \stack{struct-sys +n}{} Terminate definition of a structure started by \word{BEGIN-STRUCTURE}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}. \begin{implement} % I.10.6.2.---- END-STRUCTURE \textdf{Terminate definition of a structure.} \word{:} \word{END-STRUCTURE}\tab\word{bs} addr n -{}- \\ \tab \word{SWAP} \word{!} \word{;} \tab[4.2]\word{bs} set len \end{implement} \end{worddef} \newpage \begin{worddef}{1518}{FIELD:}[field-colon][X:structures] \item \stack{n_1 "name"}{n_2} Skip leading space delimiters. Parse \param{name} delimited by a space. \param{Offset} is the first cell aligned value greater than or equal to \param{n_1}. \param{n_2 = offset + 1} cell. Create a definition for \param{name} with the execution semantics given below. \execute[name] \stack{addr_1}{addr_2} Add the \param{offset} calculated during the compile-time action to \param{addr_1} giving the address \param{addr_2}. \see \wref{facility:+FIELD}{+FIELD}, \wref{facility:BEGIN-STRUCTURE}{BEGIN-STRUCTURE}, \\ \wref{facility:END-STRUCTURE}{END-STRUCTURE}, \rref{facility:FIELD:}{}. \begin{rationale} Create an aligned single-cell field in a data structure. The various \emph{x}\texttt{FIELD:} words provide for different alignment and size allocation. The \emph{x}\texttt{FIELD:} words could be defined as: \begin{tabbing} \tab \= \tab[6] \= \tab[22] \= \tab[5] \= \tab[5.2] \= \kill \> \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{;} \\ \setwordlist{floating} \> \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{;} \setwordlist{facility} \end{tabbing} \end{rationale} \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{1740}[01]{K-ALT-MASK}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[02]{K-CTRL-MASK}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[03]{K-DELETE}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[04]{K-DOWN}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[05]{K-END}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[06]{K-F1}[k-f-1][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[07]{K-F10}[k-f-10][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[08]{K-F11}[k-f-11][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[09]{K-F12}[k-f-12][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[10]{K-F2}[k-f-2][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[11]{K-F3}[k-f-3][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[12]{K-F4}[k-f-4][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[13]{K-F5}[k-f-5][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[14]{K-F6}[k-f-6][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[15]{K-F7}[k-f-7][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[16]{K-F8}[k-f-8][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[17]{K-F9}[k-f-9][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[18]{K-HOME}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[19]{K-INSERT}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[20]{K-LEFT}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[21]{K-NEXT}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[22]{K-PRIOR}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[23]{K-RIGHT}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[24]{K-SHIFT-MASK}[][X:ekeys] \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}. \end{worddef} \begin{worddef}{1740}[25]{K-UP}[][X:ekeys] \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}. \end{worddef} % ------------------------------------------------------------------- \begin{worddef}{1905}{MS} \item \stack{u}{} Wait at least \param{u} milliseconds. \note The actual length and variability of the time period depends upon the {im\-ple\-ment\-ation-de\-fin\-ed} resolution of the system clock and upon other system and computer characteristics beyond the scope of this standard. \see \rref{facility:MS}{}. \begin{rationale} % A.10.6.2.1905 MS 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. \end{rationale} \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\}, \param{+n_5} is the month \{1{\ldots}12\} and \param{+n_6} is the year (e.g., 1991). \see \rref{facility:TIMEandDATE}{}. \begin{rationale} % A.10.6.2.2292 TIME&DATE Most systems have a real-time clock/calendar. This word gives portable access to it. \end{rationale} \end{worddef}