Technical Notes
OverviewBecause of its power and flexibility, the scripted I/O system virtually eliminates the need to call data conversion and console I/O functions directly. Using this system, a single output script can display text, change text attributes, output aligned numeric data, and draw complex borders anywhere on the screen. A single input script can reliably validate keyboard input or read all or part of a delimited ASCII file whether or not all fields in a particular record have been written.
Scripted I/O is also remarkably easy to learn and use.
Scripts are byte strings consisting of characters and script codes. Script codes are interpreted as the script is processed; characters are processed without interpretation. Script codes may be followed by up to three 8-bit arguments per code to control the behavior of the code.
Script codes are 1, 2, or 3-byte values which have as their first byte a value in the range 0x00-0x0F, 0x7F, or 0xE0-0xFF (for _cput_script, the ranges are 0x00-0x1F, 0x7F-0xAF, or 0xE0-0xFF). Arguments always follow their assigned script codes and may assume any value except 0xFF (0xFF may be specified by inserting 0xFF twice in succession). All other values which are encountered in a script where a script code is expected are characters (0x10-0x7E and 0x80-0xDF; _cput_script treats values in the range 0x20-0x7E and 0xB0-0xDF as characters). Characters are processed without interpretation. Script codes are provided which allow literal characters or strings to be specified with values which would normally correspond to script codes.
To simplify the creation of scripts, script codes and their arguments are assigned to equates in SCRIPT.H. Examples of script code and argument equates are _END (0x00), __CHAR_F (0xFE,0xE2), and _Cdigits (0x1F). The naming convention is explained in Script Codes: Code/Argument Naming Convention, in this chapter.
Parameter lists are integer arrays which contain word-aligned immediate values and/or pointers to values. The input or output script specifies the size, type, and relative order of each expected parameter in the parameter list (e.g., byte, int, float, near, far). Entries in parameter lists are used sequentially, one at a time, as codes are encountered in the input or output script.
All of these functions support script codes for script flow control, formatted data conversion, and data synchronization. Only _cput_script supports all of the console I/O codes. _put_script supports a very limited subset of the console I/O codes (_BEL, _BS, _TAB, _LF, and _CR). _hput_script and _sput_script do not support console I/O codes at all. Unsupported console I/O codes are treated as characters.
The _v?put_script functions provide the same functionality as the _?put_script functions, except that they expect a pointer to a parameter list instead of a list of arguments. This is the same method that is used to reference parameter lists in the assembly version of the _?put_script functions.
Each of these functions allocates a 128-byte internal buffer on the stack which is used to perform formatted data conversion. The buffer is released when the function returns.
The _v?get_script functions provide the same functionality as the _?get_script functions, except that they expect a pointer to a parameter list instead of a list of arguments. This is the same method that is used to reference parameter lists in the assembly version of the _?get_script functions.
All of these functions support script codes for script flow control, formatted data conversion, and data synchronization. Console I/O codes are not supported and are treated as characters.
Parameter Lists
Parameter lists are integer arrays of variables or values which are required to process scripts. Each element in a parameter list is a word-aligned pointer or immediate value. This word alignment is automatically enforced by the compiler if the arguments in the parameter list are passed as a variable-length argument list.
All scripted I/O functions except the _v..._script functions expect the parameters in the parameter list to be specified as arguments to the scripted I/O function. The _v..._script functions expect a pointer to the parameter list; if the pointer value is -1, no parameter list is used when the script is processed.
In the following code sample, a parameter list is passed using immediate arguments to _cput_script, and an equivalent parameter list is passed to _vput_script using a pointer:
...
float num = 1.23e5;
struct param_list {
float *xloc;
int pflags;
} params = {&num, (int)*_2_Fix_Round};
...
_cput_script("Output float: "_FLOAT_P _30 _Arg _Currency_Thous, /* script */
&num, _2_Fix_Round); /* parameter list */
...
_vcput_script("Output float: "__FLOAT_P _30 _Arg _Currency_Thous, /* script */
¶ms); /* parameter list */
...
The first comma (",") separates the script string from the parameter list. With the _cput_script function the parameter list is automatically word-aligned by the compiler since the parameters are passed on the stack. However, every parameter in the parameter list for the _vput_script function must be word-aliged when it is declared. For this reason, even though the pflags parameter is a byte, it is defined as an int in the param_list structure to enforce word alignment.
WARNING! Parameter lists must be created with care. The results can be entertaining-or disastrous-if a parameter list contains insufficient or incorrect parameters or is improperly constructed. Addresses in parameter lists are simply assumed to be correct-if they aren't, data will be written to (or read from) the specified addresses anyway.
WARNING! In input scripts, input variables must be large enough to hold the specified data or subsequent data may be overwritten. When reading strings, the field width (width) specified with the data conversion code must not exceed the defined length of the string variable minus one byte for the terminal NULL.
The near pointer segment is assumed to be the default data segment (where global and static non-far data are located). The near pointer override cannot be used with the HUGE memory model.
-1 may be used to indicate a NULL parameter when a pointer is expected in the parameter list. When a pointer value of -1 is encountered, a NULL parameter is assumed by the script for that parameter and script processing continues normally.
Input scripts and output scripts are similar, but they have their differences. Although output scripts support all codes supported by input scripts, input synchronization and data conversion codes are interpreted differently. This allows a single script to be used interchangeably to read and write the same data. Differences in interpretation are explained where the codes are defined.
Console I/O codes are only supported in output scripts. Furthermore, the degree of console I/O support depends on the output device supported by the specific scripted output function.
When a script is executed, it is processed a code or character at a time until the script has been exhausted. Scripts are normally processed sequentially. However, the flow of the script may be modified using flow control codes (e.g., _REP, __CALL...). Codes are interpreted as they are encountered; characters are normally processed without interpretation.
A Spontaneous Assembly script looks significantly different than an equivalent printf string. This difference is intentional. While printf() strings require less source code, scripted I/O scripts produce less executable code, they execute faster, and they are more powerful than their C counterparts.
Combining Scripts and Parameter Lists
Each script is processed using the parameter list which is specified when the scripted I/O function is called. If a parameter list offset of -1 is specified, then no parameter list is used when the script is processed. If a script is called from another script (__CALL... or __CHAIN...), then a new parameter list is usually specified. If no new parameter list is specified (-1 is specified for the address), then the calling script's parameter list is used to process the called script.
The following example demonstrates a script, including a __CHAIN to a new script without specifying a new parameter list:
#include "script.h"
...
int time = 17;
float xloc = 12.7, yloc = -234.0, momentum = 159.755;
char m_scipt[] = "\n\rMomentum: "__FLOAT_P _10 _2_Fix_Round _Ralign " Kgm";
...
_cput_script("\n\rData after elapsed time of "__CHAR_P _Nolimit _Default" seconds:"
"\n\rX position: "__FLOAT_P _8 _2_Fix_Round _Ralign " m"
"\n\rY position: "__FLOAT_P _8 _2_Fix_Round _Ralign " m"
__CHAIN, &time, &xloc, &yloc, m_script, -1, &momentum);
...
This example produces the following output:
Data after elapsed time of 17 seconds:
X position: 12.70 m Y position: -234.00 m Momentum: 159.76 KgmThe Global SIOOPTS Structure
A number of global scripted I/O options are described in the current sioopts structure. These options include field overflow and pad characters, field and record delimiters for I/O synchronization, and flags for disabling various types of script error checking. The behavior of the scripted I/O functions depends on the current settings for these options.
The address of the current sioopts structure is maintained in sio_addr (a global pointer to the sioopts structure). By changing the address of this pointer to a new sioopts structure, the behavior of the scripted I/O system can be modified at any time.
The sioopts structure is defined in SCRIPT.H as follows:
typedef struct {
char * sio_fdelim; /* address of ASCIIZ field delim string (-1=NULL) */
char * sio_rdelim; /* address of ASCIIZ record delim string (-1=NULL) */
char sio_ovchr; /* field overflow character ("*") */
char sio_padchr; /* field pad char (for L,R,C alignment) (SPACE) */
char sio_eflags; /* error check flags (disable/enable) (0) */
} sioopts;
The default SIOOPTS structure is declared in the Spontaneous Assembly library with the default valuess shown in the comments above.
Field and record delimiters are used to enable field/record synchronization (see Scripted Input: Data Synchronization). Field/record synchronization is enabled only if non-NULL field and/or record delimiters are defined. (A NULL delimiter string is specified either with an address of -1 or by pointing to an empty string.) The string addresses are stored as near pointers in small data models (assumes DS=SS) and as far pointers in large data models.
The field overflow character is used to handle the field overflow condition when field overflow checking is disabled. On output, this character is used to write a field which is too narrow for the specified data; on input, this character is treated as an overflowed field indicator. The pad character is used for left, right, and center alignment padding of output values as well as skipping of pad characters during scripted input.
Field overflow checking may be enabled or disabled along with field underflow, numeric overflow, numeric underflow, character validation, and date/time validation by setting or clearing the appropriate bits in the sio_eflags field, as follows:
The dtcopts structure is relied on when date and time strings are processed. This structure specifies the date format, date delimiter, time format, and time delimiter defaults for the current country as well as the 100ths of seconds delimiter and custom AM/PM strings to be used with 12-hour time format. The location of the current (active) dtcopts structure is maintained in the dtc_addr variable. See the Date/Time Manipulation technical notes for a detailed explanation of the dtcopts structure.
Scripted Output Explained
Scripted output is performed by passing output scripts to the _?put_script functions. Depending on which function is used, the output destination may be STDOUT, the screen (console I/O system), a file, or a buffer (in ASCIIZ format). Scripted output is ideal for displaying screens or values as well as for writing data in human-readable form which will subsequently be read using scripted input.
With scripted output, characters are written out whenever characters, strings, or data conversion codes are encountered in the script. Output always takes place at the position specified by the output pointer (e.g., cursor, file pointer, or string pointer). The output pointer is always advanced as data is written to the output destination.
If the output device is the screen (console I/O system), then the output pointer (cursor) is advanced in the current output direction after each character is written. Characters are always written to the active screen at the current cursor position using the current text attribute. The cursor position, cursor advance direction, and text attribute may be modified within an output script by using the supported console I/O script codes.
If a data conversion code is encountered in an output script, the next variable is read from the parameter list and its value is interpreted and written out as specified by the arguments to the data conversion code. No type checking of parameters is performed. Unused parameters at the end of a parameter list are ignored.
Output of numeric types is performed by converting numeric values to ASCII strings and formatting the result as specified in the script. Character and string types are output directly without any formatting except alignment and case conversion, if specified. Output always takes place at the current output position (e.g., cursor position or file position).
The results are undefined if the parameter list contains insufficient or incorrect parameters.
As a script is processed, the scripted input function maintains an input pointer which indicates the next input character to be processed from the input source. Characters are processed sequentially, one at a time, from the start to the end of the input source. The input pointer is always advanced past any data which is converted and read from the input source. The input pointer may also be synchronized with the script by matching, skipping, or advancing to selected input characters.
Only a single line of input data is read each time a scripted input function is called if the input source is STDIN or the keyboard; data is read a character at a time if the input source is a handle or a string. Once read, input characters are interpreted or skipped as specified in the input script. Unprocessed data at the end of the current line is discarded if the input source is STDIN or the keyboard.
WARNING! Scripted input parameter lists must be produced with care. The results can be disastrous if an input parameter list contains insufficient or incorrect parameters. Addresses in parameter lists are simply assumed to be correct-if they aren't, data will be written to the specified addresses anyway.
WARNING! Since no type checking or bounds checking of parameters is performed, it is important to ensure that each input parameter is large enough to hold its intended data or subsequent data may be overwritten. To avoid problems, the input parameter type should always match the data conversion code in the script. Furthermore, when reading strings, the specified string field width (width) must not exceed the defined length of the string variable minus one byte for the terminal NULL.
Numeric types are read by first stripping off special-purpose formatting characters (such as currency signs and thousands separators) and then converting the remaining ASCII digits. Character and string types are read directly without any formatting except case conversion, if specified.
Most of the formatting options specified with the width, precision, nformat, and other format arguments are significant during scripted input. These options are interpreted in a manner which allows data to be written and read using the same or similar scripts.
For example, the width argument limits the number of characters which will be processed on input, including leading and trailing pad characters and field overflow characters. precision limits the number of digits which will be converted to the right of the decimal point. The _Trunc and _Round options associated with precision are also significant-they determine how unused trailing digits are rounded. The _Fill option is significant (as described below). The _Fix and _Float options are ignored during scripted input.
Alignment options (specified with nformat, sformat, and align) are also significant in an input script. If any kind of alignment is specified, then the appropriate leading and/or trailing pad characters are skipped in a manner consistent with the alignment method. For example, if _Lalign is specified, then: 1) the value is read, and 2) trailing pad characters are skipped. If _Calign is specified, then 1) pad characters are skipped, 2) the value is read, and 3) any remaining pad characters are skipped. The _Fill precision option causes an appropriate number of space characters to be skipped immediately after the last decimal place (but before the exponent, if any).
Data may be successfully read with less precision than the precision at which it was written as long as the input width is greater than or equal to the output width. This is true even if field and record synchronization is not enabled. This is possible because all consecutive numeric characters within the field specified by width are skipped on input, even if some of those characters are not actually converted. However, when alignment characters are also skipped, no more than width characters will be processed for any given read, including the value itself and any pad characters.
Scripted Input: Interpretation of Leading/Trailing Strings
Leading/trailing strings and field/record delimiter strings are defined in the current dcopts, dtcopts, and sioopts structures. These option strings receive special consideration during scripted input. When an attempt is made to match the input data to any of these strings, a case-independent match is performed (similar to _str_cmpi). In addition, space characters (0x20) within these option strings are treated as optional characters and non-space characters are treated as required characters. All characters in these option strings are processed during scripted output. A default string is used if no string is defined, according to the following table:
Global String Default Value
Only those subfields specified in the dformat and tformat arguments are actually read and stored; the remaining fields are neither read nor stored. This means that only the specified portions of the unsigned long destination variable are modified on a successful read. It also means that the input value must be in the specified format or the field values may be interpreted incorrectly.
An invalid date/time error is returned if fewer fields were read than were expected, a required field is zero or empty, or no interpretable characters were found in a field. For example, if three date fields were expected then "//92", "2/A/92", or "11/12" would generate invalid date/time errors. The invalid date/time error is returned if numeric overflow occurs in any required field (i.e., the read value exceeds the maximum allowed value for that field). If date/time validation is disabled, then the entire date string is skipped in the above examples.
If a date or time string contains more fields than are required for the read, the leading fields must match the specified format and trailing fields are skipped. For example, if _Mdy_Noyr were specified for dformat, then "12/31" and "12/31/95" would both be read correctly. If _Mdy_Noday were specified for dformat (only month and year expected), an input string of "12/31" would be interpreted as representing month 12 of the year 2031.
The time format (12- or 24-hour) specified in tformat is significant. If 12-hour format is specified, then the scripted input function requires a am/pm indicator after the time. This indicator must match the am/pm strings specified in the current date/time conversion options structure (dtcopts), or it must match "a", "p", "am", or "pm" (case-insensitive comparison) with at most one space character between the last digit of the time and the am/pm indicator. An invalid date/time error is returned if no am/pm indicator is found when 12-hour time format has been specified. If 24-hour format is specified, then no attempt is made to match am/pm strings, nor are am/pm strings skipped if they are present. If _Cntryhr format is specified for tformat, then either 12-hour or 24-hour format is expected, as described above (depending on the setting in the current dtcopts structure). If _Flexhr format is specified for tformat, then the date is read in either 12-hour or 24-hour format, depending on the format encountered. An invalid date/time error is returned if the hour value is greater than 12 and a trailing am/pm string is encountered; or, if date/time validation is disabled, then the entire time string is skipped, including the trailing am/pm string.
Year values in date strings are read in whatever format is encountered (2-digit or 4-digit) regardless of the format specified in the dformat argument. When 2-digit year values are converted, values from 80 to 99 are assumed to represent the years 1980 through 1999; other values represent years from 2000 to 2079.
Overflow and underflow conditions generate errors if and only if error checking has been enabled by setting the appropriate flags in the current sioopts structure. By default, all types of underflow and overflow checking are disabled. If a non-checked underflow or overflow occurs, then the read is either skipped (in the case of field underflow or overflow) or a reasonable value is returned (in the case of numeric overflow or underflow) and the entire read value is skipped.
Field underflow (no readable value present) occurs when an unsuccessful attempt is made to read a value using an input script. If field underflow error checking is disabled, field underflow is handled by ignoring the read-no value is stored in the variable. This allows default values to be handled by initializing the destination variables before the input script is processed. (If the end of the input data is encountered when a value is expected then an end-of-input condition is returned. The programmer must decided whether or not to treat this condition like field underflow by ignoring it.)
Field overflow (field overflow characters found) occurs when an attempt is made to read a field which begins with a field overflow character. If field overflow checking is disabled, field overflowis handled the same way field underflow is handled-by ignoring the read. In addition, the unreadable characters are also skipped by advancing the input pointer past no more than width consecutive field overflow characters (where width is the width specifier associated with the data conversion script code). The field overflow character is defined in the current sioopts structure.
Numeric underflow (value too small) occurs when an attempt is made to read a value which cannot be represented in the specified data type because it is too close to zero. If numeric underflow checking is disabled, numeric underflow is handled by returning a value of zero and skipping the unreadable input value. For example, if an attempt were made to read "1.2345e-6789" using __FLOAT, then 0 would be returned and the input pointer would be advanced past the entire input value. The input value is skipped by advancing the input pointer past no more than width consecutive digits and expected formatting characters.
Numeric overflow (value too large) occurs when an attempt is made to read a number which cannot be represented in the specified data type because it is too close to +/-infinity. This includes any attempt to read a negative value into an unsigned variable. Numeric overflow checking is only supported for floating-point numbers, byte integers, word integers, and fixed-point word values. If numeric overflow checking is disabled, then an undefined value is stored, the input pointer is advanced past the input value, and processing continues. The input value is skipped by advancing the input pointer past no more than width consecutive digits and formatting characters. Only expected formatting characters are skipped (as specified in the current dcopts, dtcopts, and sioopts structures and in the nformat argument).
Technically, an attempt to read a floating-point value such as "0.0123" into an integer is not an underflow condition, though the results are the same. If any non-integer value is read into an integer, then the closest integer value is returned (i.e., 0 in the case of "0.0123") and the input pointer is advanced past the entire input value. As before, the input value is skipped by advancing the input pointer past no more than width consecutive digits and expected formatting characters.
Invalid date/time errors and invalid character errors may be suppressed by setting the appropriate flag in the current sioopts structure. If suppressed, then these errors are handled by ignoring the read-no value is stored-and skipping the invalid input data in a manner which is consistent with the expected input. For example, if a date is expected in "MM/DD/YY" format but only "MM/DD" is encountered, then the "MM/DD" data is skipped; if only a single numeric value is encountered then that value is skipped. An unmatched required character is ignored by treating it as an optional character and continuing-no input data is skipped.
If field/record synchronization is enabled, the scripted input functions naturally subdivide input data into records and fields: input data is read and processed up to the next field or record delimiter, but never beyond, unless the input script explicitly advances to the next field or record. By writing field delimiters between data items and then advancing between fields after every read, the input script will always remain synchronized with the input data. This method also allows any number of input values to be defaulted by simply writing field or record delimiters with nothing between them.
Script codes are also provided to allow manual synchronization by skipping arbitrary characters up to and including a specified character, string, or character in a character set.
By default, field/record synchronization is disabled. It may be enabled by specifying record and field delimiters in the current sioopts structure. These delimiters are specified as ASCIIZ strings. Most commonly, a CR/LF pair is used as the record delimiter (0x0D followed by 0x0A). Some common field delimiters are the comma (0x2C), semicolon (0x3B), and the vertical bar (0x7C) characters.
Fixed-point values are commonly used to keep track of currency (dollars) with two digits to the right of the decimal point. When used in this way, the fixed-point integer values are treated as representing cents (hundredths of dollars). For example, a fixed-point integer value of 10025 would represent $100.25.
Fixed-point values are stored as integers with no indication of the location of the decimal point. Instead, the number of digits to the right of the decimal point must be supplied when a fixed-point value is to be read or written. The precision argument is used for this purpose. On output, precision designates the number of implied digits to the right of the decimal point when the internal, integer value is converted to fixed-point decimal ascii format. On input, precision specifies the number of implied decimal places to be read and stored as the least-significant digits in the internal, integer result.
For example, if an integer value of 12345 were output as an __FXPI with a precision of 2, then "123.45" would be output. Likewise, when reading "123.45" into an __FXPI with a precision of 2, the value stored would be 12345. If "123.45678" were read using __FXPI with a precision of 2 with the _Round option specified (_Round is the default), then an unsigned int value of 12346 would be read.
To prevent undesired rounding or truncation, special handling is performed when reading or writing fixed-point values in exponential formats (_Exp or _Flex). When exponential numbers are read using an __FXP... code they are first converted to non-exponential format before precision is interpreted. When fixed-point values are written as exponential numbers, all possible significant digits are written without padding with trailing zeros.
For example, If an unsigned long value of 123456789 were output in _Exp format with a precision of 5, the number would first be converted internally to 1234.56789 and would then be written as "1.23456789e03". If that ASCII result were then read with a precision of 5, the exponential format would first be converted (internally) to 1234.56789, then 5 digits would be read to the right of the decimal point giving a result of 123456789.
struct sstat {
char ecode; /* error condition code */
char inprocess; /* # of parameters in process */
int paramcnt; /* # of parameters processed */
char * scriptaddr; /* final script address */
int * paramaddr; /* final parameter list address
} s_status;
To facilitate debugging and error recovery, s_status.inprocess is set to 1 as each script code is encountered which requires one or more parameters from the parameter list (i.e., each script code which is assigned to an equate which begins with two underscore characters). s_status.inprocess is reset to zero and s_status.paramcnt is incremented when the code has been successfully processed.
Script error condition codes (s_status.ecode) are defined in SCRIPT.H as follows:
_cput_script(_UNSIGNED __INT_P __Arg_p _Default,...);
As this output script is processed, the following occurs:
#include "script.h"
...
if (cget_script(...) != 0) /* process keyboard input */
{
if (s_status.ecode = SE_DATE) { _put_str("date/time error."); }
if (s_status.paramcnt = 0) { _put_str("No parameters found."); }
...
}
Some of the Spontaneous Assembly script codes perform similar actions to the C script codes for printf and scanf while providing enhanced functionality over their C counterparts. However, the method of specifying precision, width, and format with the Spontaneous Assembly codes is different than with printf codes since the argument(s) always follow the code and are always declared using symbolic constants. For example, the codes "__FXPQUAD _20 _2 _Thous" would convert a quad integer to a numeric string with thousands delimiters, a precision of 2, and a maximum width of 20 characters.
This method of specifying script codes and arguments makes the Spontaneous Assembly scripting engine much more efficient than is possible with a printf-like syntax.
The scripting codes and arguments for Spontaneous Assembly are defined as strings in SCRIPT.H. Each argument only occupies a single byte in the script, no matter how many options are combined into the argument. For example, the script "__SHORT _20 _2 _Currency_Thous" is really represented as "\xEF\x14\x02\x0C" (four bytes) in the script string. Using printf, a total of six bytes are necessary to designate similar functionality ("%20.2f"), but this printf string provides no support for thousands delimiters or a currency symbol.
Flag options and ranges for each argument are specified in the script code documentation where the arguments are described. Where required, argument flags are combined with values or with each other by adding the flags and the value (if any) to form a single byte as shown in this example:
#include "script.h"
...
float num = 100000;
_put_script("Transactions: "__CHAR _3 _Default
"\n\rBalance: "__FLOAT _10 _2_Fix _Currency_Thous,10,&num);
...
In this example, _2_Fix demonstrates the case where a value is specified (2) in combination with an optional precision flag (_Fix). _Currency_Thous demonstrates a combination of nformat flags (which are not combined with a value). Flags may only be used within the arguments for which they are intended, as described in the script code documentation. All appropriate combinations of script code argument flags are defined in SCRIPT.H (see Script Codes: Formatted Data Conversion).
Wherever scripts and codes are discussed, argument names are displayed in italics, and argument names are used consistently. For example, string and charset denote an ASCIIZ string or NULL-terminated character set. script denotes any sequence of characters and/or script codes delimited with a NULL. count denotes any value in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFF. (Argument values of 0xFF are allowed only as described in the following section.)
Script code, arg(s) Parameter listDescription
Argument value limits and argument flags, as defined in this documentation, have been carefully selected to prevent any argument from inadvertently being assigned a value of 0xFF.
This naming convention makes it easy to distinguish between script codes (__CHAR, __FLOAT, _NL, and _END) and arguments (_Noalign, _Fix, _Currency, _Thous). This convention also allows scripts to be quickly scanned to determine the number of parameters required in the parameter list. For example, the previous sample script (see Script Codes: Arguments) expects only two parameters: a char value and a float value.
Script Codes: Flow Control
Normally, scripts are processed sequentially, a byte at a time, and script codes (0x00-0x1F, 0x7F-0xAF, 0xE0-0xFF) are interpreted instead of being displayed. The following codes allow this convention to be changed by allowing characters, strings, codes, and other scripts to be embedded or called and repetitively processed inside any script. These codes are defined in SCRIPT.H.
Script code, arg(s) Parameter listDescription
The following equates may be used in the script in place of any argument to specify that the argument is to be obtained from the parameter list:
When used in place of an immediate string or charset:
Script code, arg(s) Parameter listDescription
Script code, arg(s) Parameter listDescription __Arg char arg (0xFF,0xFB) (0xFF,0xFC) (0xFF,0xFD) (ptr if (0xFF,0xFE) Reads argument from __Arg_p applicable) parameter __Arg_n char * arg list instead of script. The __Arg_f char near * parameter list is arg expected to contain the word- char far * aligned char value arg (or a pointer to the char value) which is to be used as argument.The __Arg... codes always replace the entire argument. They MAY NOT be combined with argument flags.
It should be noted that characters which appear directly in input scripts are treated as required characters. If character validation is enabled (by setting the appropriate bit in the current sioopts structure) then these characters must match characters at the current input pointer position or an error is returned. To skip optional input characters, use the _SKP... codes instead.
Field and record delimiters must be defined in the current sioopts structure or no automatic field and record synchronization is performed. In the descriptions which follow, references to field and record delimiters should be ignored in the case where no delimiters have been declared.
Script code, arg(s) Parameter listDescription
These codes may be followed by as many as three parameters to specify field width, precision, and format. Symbolic constants for specifying these options are described subsequent to the code descriptions and in the reference section of the scripting functions.
Script code, arg(s) Parameter listDescription
_UNSIGNED (0xE0) Specifies that the integer or fixed-point value designated by the next code (__CHAR..., __ASCINT..., __FPXQUAD..., etc.) is to be treated as an unsigned value. Unless _UNSIGNED is specified, integer values are assumed to be signed.
__CHAR,width char (0xE1) (0xE2) (0xFD,0xE2),nformat char * (0xFE,0xE2)
__CHAR_P,width char near * Processes a char value as a decimal,nformat char far * ASCII
__CHAR_N,width string. In an output script, the,nformat char value is
__CHAR_F,width formatted as specified by nformat,nformat and written as an ASCII string. In an input script, a formatted char value is read at the current input pointer position, with nformat indicating allowable input formats. No more than width characters are written or skipped.
__INT,width int (0xE3) (0xE4) (0xFD,0xE4),nformat int * (0xFE,0xE4)
__INT_P,width int near * Processes an int value as a decimal,nformat int far * ASCII
__INT_N,width string. In an output script, the,nformat int value is
__INT_F,width formatted as specified by nformat,nformat and written as an ASCII string. In an input script, a formatted int value is read at the current input pointer position, with nformat indicating allowable input formats. No more than width characters are written or skipped.
__LONG,width, long (0xE5) (0xE6) (0xFD,0xE6) nformat (0xFE,0xE6) __LONG_P,width, long * Process a long value as a decimal nformat ASCII string. __LONG_N,width, long near * In an output script, the long value nformat is formatted __LONG_F,width,nformat long far * as specified by nformat and written as an ASCII string. In an input script, a formatted long value is read at the current input pointer position, with nformat indicating allowable input formats. No more than width characters are written or skipped. __QUAD,width, quadptr (0xE8) (0xE8) (0xFD,0xE8) nformat (0xFE,0xE8) __QUAD_P,width,nformat Process a quad value as a decimal quadptr ASCII string. __QUAD_N,width, In an output script, the quad value nformat is formatted __QUAD_F,width, quadnptr as specified by nformat and written nformat as an ASCII string. In an input script, a quadfptr formatted quad value is read at the current input pointer position, with nformat indicating allowable input formats. No more than width characters are written or skipped. __ASCCHAR,width,radi char (0xFF,0x20) (0xFF,0x21) x,align (0xFD,0xFF,0x21) __ASCCHAR_P,width,ra (0xFE,0xFF,0x21) Processes a char dix,align value as an __ASCCHAR_N,width,rchar * ASCII string in a specified radix. adix,align In an output __ASCCHAR_F,width,ra script, the char value is aligned dix,align char near * as specified by align and written as an ASCII string in the char far * given radix. In an input script, a formatted char value in the given radix is read at the current input pointer position, with align indicating allowable input formats. No more than width characters are written or skipped. __ASCINT,width, __ASCINT_F,wid int radix,align th,radix,align __ASCINT_P,width,rad int * ix,align __ASCINT_N,width,rad int near * ix,align int far * (0xFF,0x22) (0xFF,0x23) (0xFD,0xFF,0x23) (0xFE,0xFF,0x23) Processes an int value as an ASCII string in a specified radix. In an output script, the int value is aligned as specified by align and written as an ASCII string in the given radix. In an input script, a formatted int value in the given radix is read at the current input pointer position, with align indicating allowable input formats. No more than width characters are written or skipped. __ASCLONG,width,radix, long (0xFF,0x24) (0xFF,0x25) align (0xFD,0xFF,0x25) __ASCLONG_P,width,radix, (0xFE,0xFF,0x25) Processes a long align long * value as an __ASCLONG_N,width,radix, ASCII string in a specified radix. dix,align In an output __ASCLONG_F,width,radix, long near * script, the long value is aligned align as specified by align and written as an ASCII long far * string in the given radix. In an input script, a formatted long value in the given radix is read at the current input pointer position, with align indicating allowable input formats. No more than width characters are written or skipped. __ASCQUAD, quad (0xFF,0x27) (0xFF,0x27) width,radix,align (0xFD,0xFF,0x27) __ASCQUAD_P, (0xFE,0xFF,0x27) Processes a quad width, quadptr value as an radix,align ASCII string in a specified radix. __ASCQUAD_N, In an output width, quadnptr script, the quad value is aligned radix,align as specified by __ASCQUAD_F, align and written as an ASCII width, quadfptr string in the radix,align given radix. In an input script, a formatted quad value in the given radix is read at the current input pointer position, with align indicating allowable input formats. No more than width characters are written or skipped. __FXPINT,width,precision, int (0xE9) (0xEA) (0xFD,0xEA) nformat (0xFE,0xEA) __FXPINT_P,width,precision, Processes a fixed-point int integer, nformat int * value as a __FXPINT_N,width,pre decimal ASCII string. In an output cision,nformat int near * script, the int __FXPINT_F,width,pre value is formatted as specified by cision,nformat nformat and int far * written as an ASCII string with precision digits forced to the right of the decimal point. In an input script, a formatted, fixed- point int value is read at the current input pointer position and stored as an integer value with exactly precision digits assumed to the right of the decimal point. No more than width characters are written or skipped. __FXPLONG,width,precision, long (0xEB) (0xEC) (0xFD,0xEC) nformat (0xFE,0xEC) __FXPLONG_P,width,precision, Processes a fixed-point long nformat long * integer value as a __FXPLONG_N,width,precision, decimal ASCII string. In an output nformat script, the __FXPLONG_F,width,precsion, long near * long value is formatted as nformat specified by nformat and written as an ASCII string with precision long far * digits forced to the right of the decimal point. In an input script, a formatted, fixed-point long value is read at the current input pointer position and stored as an integer value with exactly precision digits assumed to the right of the decimal point. No more than width characters are written or skipped. __FXPQUAD,width,prec__FXPQUAD_F,wi quadptr ision,nformat dth,precision, __FXPQUAD_P,width,p nformat quadptr recision,nformat __FXPQUAD_N,width,p quadnptr recision,nformat quadfptr (0xEE) (0xEE) (0xFD,0xEE) (0xFE,0xEE) Processes a fixed-point quad integer value as a decimal ASCII string. In an output script, the quad value is formatted as specified by nformat and written as an ASCII string with precision digits forced to the right of the decimal point. In an input script, a formatted, fixed-point quad value is read at the current input pointer position and stored as an integer value with exactly precision digits assumed to the right of the decimal point. No more than width characters are written or skipped. __FLOAT,width,precis float (0xEF) (0xF0) (0xFD,0xF0) ion,nformat (0xFE,0xF0) __FLOAT_P,width,prec Processes a float value as a ision,nformat float * decimal ASCII __FLOAT_N,width,prec string. In an output script, the ision,nformat float value is __FLOAT_F,width,prec float near * formatted as specified by nformat ision,nformat and written as an ASCII string. In an input float far * script, a formatted float value is read at the current input pointer position, with nformat indicating allowable input formats. No more than precision digits are stored or written to the right of the decimal place, and no more than width total characters are written or skipped. __DOUBLE,width,preci double (0xF1) (0xF2) (0xFD,0xF2) sion,nformat (0xFE,0xF2) __DOUBLE_P,width,pre Processes a double value as a cision,nformat double * decimal ASCII __DOUBLE_N,width,pre string. In an output script, the cision,nformat double value is __DOUBLE_F,width,pre double near * formatted as specified by nformat cision,nformat and written as double far * an ASCII string. In an input script, a formatted double value is read at the current input pointer position, with nformat indicating allowable input formats. No more than precision digits are stored or written to the right of the decimal place, and no more than width total characters are written or skipped. __LDOUBLE,width,prec long double (0xF3) (0xF4) (0xFD,0xF4) ision,nformat (0xFE,0xF4) __LDOUBLE_P,width,pr Processes a long double value as a ecision,nformat long double * decimal __LDOUBLE_N,width,pr ASCII string. In an output script, ecision,nformat long the long __LDOUBLE_F,width,p double double value is formatted as recision,nformat near * specified by nformat and written as an ASCII long double string. In an far * input script, a formatted long double value is read at the current input pointer position, with nformat indicating allowable input formats. No more than precision digits are stored or written to the right of the decimal place, and no more than width total characters are written or skipped. __BCD,width, bcdptr (0xFF,0x29) (0xFF,0x29) nformat (0xFD,0xFF,0x29) __BCD_P,width, (0xFE,0xFF,0x29) Processes a 10- nformat bcdptr byte packed __BCD_N,width, bcd value as a decimal ASCII nformat bcdnptr string. In an __BCD_F,width, output script, the bcd value is nformat bcdfptr formatted as specified by nformat and written as an ASCII string. In an input script, a formatted bcd value is read at the current input pointer position, with nformat indicating allowable input formats. No more than width total characters are written or skipped.Refer to the Data Conversion technical notes for information about the bcd and bcdptr typedefs.
__NEARPTR,width, __NEARPTR_N,wi void near * sformat dth,sformat void near * * __NEARPTR_P,width,sf__NEARPTR_F,wi ormat dth,sformat void near * near * void near * far * (0xFF,0x2A) (0xFF,0x2B) (0xFD,0xFF,0x2B) (0xFE,0xFF,0x2B) Processes a near pointer (offset) as a four-digit hexadecimal number. In an output script, the near pointer value is formatted as specified by nformat and written as a 4-digit hexadecimal string. In an input script, a formatted, 4-digit hexadecimal near pointer is read at the current input pointer position, with nformat indicating allowable input formats. No more than width total characters are written or skipped. __FARPTR,width, void far * (0xFF,0x2C) (0xFF,0x2D) sformat void far * * (0xFD,0xFF,0x2D) __FARPTR_P,width, (0xFE,0xFF,0x2D) Processes a far sformat void far * pointer near * (segment:offset) in 4-digit:4-digit __FARPTR_N,width, hexadecimal sformat void far * format. In an output script, the far * far pointer value is formatted as specified by __FARPTR_F,width, nformat and written sformat as a 4-digit:4-digit hexadecimal string. In an input script, a formatted, 4- digit:4-digit hexadecimal far pointer is read at the current input pointer position, with nformat indicating allowable input formats. No more than width total characters are written or skipped. __DATE,width,dformat long (0xF5) (0xF6) (0xFD,0xF6) ,sformat (0xFE,0xF6) __DATE_P,width,dform Processes date information in a at,sformat long * long value as an __DATE_N,width,dform ASCII date string. In an output at,sformat script, the long __DATE_F,width,dform long near * date information is formatted as at,sformat specified by dformat and sformat and written as long far * an ASCII string. In an input script, a formatted date is read at the current input pointer position into the long date variable, with dformat and sformat indicating allowable input formats. No more than width total characters are written or skipped. __TIME,width,tformat long (0xF7) (0xF8) (0xFD,0xF8) ,sformat (0xFE,0xF8) __TIME_P,width,tform Processes time information in a at,sformat long * long value as an __TIME_N,width,tform ASCII time string. In an output at,sformat script, the long __TIME_F,width,tform long near * time information is formatted and at,sformat written as specified by tformat and sformat long far * and written as an ASCII string. In an input script, a formatted time is read at the current input pointer position into the long time variable, with tformat and sformat indicating allowable input formats. No more than width total characters are written or skipped. __CHARACTER, char (0xF9) (0xFA) (0xFD,0xFA) width,sformat char * (0xFE,0xFA) __CHARACTER_P, char near * Processes a single, formatted ASCII width,sformat char far * character. __CHARACTER_N, In an output script, the specified width,sformat ASCII __CHARACTER_F, character is formatted, aligned, width,sformat and written as specified by sformat within a total field width of width characters. In an input script, an ASCII character is read from the current input pointer position into the specified variable, with sformat indicating allowable input formats. No more than width total characters are written or skipped. __STRING, char * (0xFB) (0xFC) (0xFD,0xFC) width, char * (0xFE,0xFC) sformat char near * Processes a formatted string. In an __STRING_P, char far * output script, width, the specified string is formatted, sformat aligned, and __STRING_N,width,sform written as specified by sformat at within a total __STRING, width, sformat field width of width characters. In an input script, a string is read from the current input pointer position into the specified string variable, with sformat indicating allowable input formats. No more than width total characters are written or skipped.As used above, width denotes the maximum width of the output field in characters and precision denotes the maximum or required number of numeric digits to the right of the decimal point. radix denotes the radix of the ASCII numeric value. dformat and tformat denote date and time formatting options, and the nformat and sformat arguments denote numeric and string formatting options.
width, precision, and radix are specified directly in the script as single-byte binary values combined with their corresponding formatting options, defined below. Options are combined with values by adding or ORing the option flags with the values. To deal with compiler limitations, all the possible combinations of options and values have been predefined in SCRIPT.H. For example, a precision of _23_Fix specifies a fixed precision of 23 digits to the right of the decimal point.
nformat, sformat, dformat, tformat, and align are specified directly in the script as single-byte values and are composed entirely of formatting option flags. These flags (defined below) have been defined for all possible flag combinations in SCRIPT.H. For example, an nformat of _Noexp_Right_Thous specifies right-aligned, non-exponential output with thousands separators inserted to the left of the decimal point.
WARNING! For Microsoft compilers, the /EP option must be used when the symbolic constants in SCRIPT.H are used to define scripts. This requirement arises because many of the symbolic constants exceed the preprocessor default width of 32 characters. If the /EP switch is used within the PWB, the preprocessed file will be compiled and linked automatically. If the /EP switch is used on the command line, the resulting .I file can be compiled and linked manually.
The following formatting options apply to nformat, sformat, and align:
The following options apply to dformat:
The following options apply to tformat:
The following options apply to precision:
The following options apply to width:
The following options apply to radix:
Note that when a console I/O code modifies the behavior of the console I/O system, those changes remain in effect after the script has been processed. For example, if the _ATTR code is used to select a new text attribute, then that attribute remains in effect even after the script has been processed. See Script Codes: Saving/Restoring the Console I/O State for additional codes which may be used to preserve the console I/O state within a script.
Script code, arg(s) Parameter listDescription _BEL - (0x07) Beep. Same as _cput_beep. _BS - (0x08) Backspace. Moves the cursor once in the direction opposite the current cursor advance direction. Same as _move_back. _TAB - (0x09) Tab. Advances the cursor to the next screen column position which is a multiple of eight columns from the left edge of the current clipping region. Same as _goto_x((int(x/8)+1)*8). _LF - (0x0A) Line feed. Moves the cursor down one row without changing the current column. Same as _move_down. _NL - (0x0B) Newline. Same as _cput_newline. _FF - (0x0C) Form feed. Clears the entire current window or screen (even if a clipping region is enabled). _CR - (0x0D) Carriage return. Moves the cursor to the left-most column of the current clipping region. Same as _goto_left. _NEXT - (0x16) Move cursor to next cursor position. Moves the cursor once in the current cursor advance direction. Same as _move_next. _UP - (0x17) Move cursor up. Moves the cursor up one row. Same as _move_up. _RIGHT - (0x18) Move cursor right. Moves the cursor right one column. Same as _move_right. _LEFT - (0x19) Move cursor left. Moves the cursor left one column. Same as _move_left. _DOWN - (0x1A) Move cursor down. Moves the cursor down one row. Same as _move_down. _AFILLEOL,attr - (0xFF,0x40) Attribute fill to end of line. Sets all attributes from the cursor position to the end of the current line to a specified attribute. The cursor position remains unchanged. Same as _afill_eol. _AFILLINE,attr - (0xFF,0x41) Attribute fill line. Sets all attributes on the current line to a specified attribute. The cursor position remains unchanged. Same as _afill_line. _AFILLN,attr,count - (0xFF,0x42) Attribute fill N positions. Sets a specified number of attributes on the current line to a specified attribute. The cursor position remains unchanged. Same as _afill_n. _AFILLREG,attr - (0xFF,0x43) Attribute fill region. Sets all attributes in the current clipping region to a specified attribute. The cursor position remains unchanged. Same as _afill_region. _ATTR,attr - (0x10) Set text attribute. Sets the current text attribute (the attribute used to display text) to a specified value. Same as _set_attr. _ATTRF,aflags - (0xFF,0x44) Set attribute flags. Sets the current attribute flags to indicate if bold, blink, or background bold attributes should be forced when displaying text in the current text attribute. Same as _set_attrflags. _BKBOLDM - (0xFF,0x45) Set background bold mode. Reprograms the active display adapter to support high-intensity background attributes instead of blinking text. Same as _set_bkboldmode. _BKBOLDON - (0x11) Background bold on. Sets the high intensity background bit in the current text attribute if currently supported by the active display adapter. Same as _bkbold_on. _BKBOLDOFF - (0x12) Background bold off. Clears the high intensity background bit in the current text attribute if currently supported by the active display adapter. Same as _bkbold_off. _BKCOLOR,color - (0x13) Set background color. Sets the background color for the current text attribute. Same as _set_bkcolor. _BLINKM - (0xFF,0x46) Set blink mode. Reprograms the active display adapter to support blinking text instead of high-intensity background attributes. Same as _set_blinkmode. _BLINKON - (0x14) Blink on. Sets the blink bit in the current text attribute if currently supported by the active display adapter. Same as _blink_on. _BLINKOFF - (0x15) Blink off. Clears the blink bit in the current text attribute if currently supported by the active display adapter. Same as _blink_off. _BOLDON - (0x1B) Bold on. Sets the bold bit in the current text attribute. Same as _bold_on. _BOLDOFF - (0x1C) Bold off. Clears the bold bit in the current text attribute. Same _as bold_off. _CLREOL - (0x1D) Clear to end of line. Clears the current line from the cursor position to the end of the line by writing space characters (0x20) in the default text attribute. The cursor position remains unchanged. Same as _clr_eol. _CLRLINE - (0x1E) Clear line. Clears the current line by writing space characters (0x20) in the default text attribute. The cursor position remains unchanged. Same as _clr_line. _CLRN,count - (0x1F Clear N positions. Clears a specified number of columns on the current line by writing space characters (0x20) in the default text attribute. The cursor position remains unchanged. Same as _clr_n. _CLRREG - (0x80) Clear region. Fills the current clipping region with space characters (0x20) in the default text attribute. The cursor position remains unchanged. Same as _clr_region. _CURSON - (0x81) Cursor on. Turns the hardware cursor on. Same as _cursor_on. _CURSOFF - (0x82) Cursor off. Turns the hardware cursor off. Same as _cursor_off. _CURSOR,end,start - (0xFF,0x47) Set cursor shape. Sets the display cursor starting and ending scan lines to specified values. Same as _set_cursor. (Note: A scan line value of 255 must be specified using the _255 or _0xFF equates.) _DATTR,attr - (0x83) Set default attribute. Sets the default attribute used for clearing, inserting, and scrolling. Same as _set_dattr. _DELLINE _ (0xFF,0x48) Delete line. Deletes the current line from the current clipping region. Lines below the current line are scrolled up and a new, blank line is scrolled in at the bottom of the clipping region. Same as _del_line. _DIRECTION,xdist,ydist- (0xFF,0x49) Set cursor advance direction. Specifies the horizontal and vertical distance which the cursor moves after each character is displayed. Same as _set_direction. (Note: a distance of -1 must be specified using the _255 or _0xFF equates.) _DIRDOWN - (0x84) Advance down. Sets the cursor advance direction to ADV_DOWN, so the cursor moves down one row after each character is displayed. Same as _set_direction (ADV_DOWN). _DIRLEFT - (0x85) Advance left. Sets the cursor advance direction to ADV_LEFT, so the cursor moves one column to the left after each character is displayed. Same as _set_direction (ADV_LEFT). _DIRRIGHT - (0x86) Advance right. Sets the cursor advance direction to ADV_RIGHT, so the cursor moves one column to the right (the default direction) after each character is displayed. Same as _set_direction (ADV_RIGHT). _DIRUP - (0x87) Advance up. Sets the cursor advance direction to ADV_UP, so the cursor moves up one row after each character is displayed. Same as _set_direction (ADV_UP). _FGCOLOR,color - (0x88) Set foreground color. Sets the foreground color for the current text attribute. Same as _set_fgcolor. _FILLEOL,char,attr - (0xFF,0x4A) Fill to end of line. Sets all characters and attributes from the cursor to the end of the current line to a specified character and attribute. The cursor position remains unchanged. Same as _fill_eol. _FILLINE,char,attr - (0xFF,0x4B) Fill line. Sets all characters and attributes on the current line to a specified character and attribute. The cursor position remains unchanged. Same as _fill_line. _FILLN,char,attr,count- (0xFF,0x4C) Fill N positions. Sets a specified number of characters on the current line to a specified character and attribute. The cursor position remains unchanged. Same as _fill_n. _FILLREG,char,attr - (0xFF,0x4D) Fill region. Sets all characters and attributes in the current clipping region to a specified character and attribute. Same as _fill_region. _GOBOTTOM - (0x89) Go to bottom margin. Moves the cursor to the bottom row of the current clipping region. Same as _goto_bottom. _GOEND - (0x8A) Go to end. Moves the cursor to the lower right corner of the current clipping region. Same as _goto_end. _GOHOME - (0x8B) Go to home. Moves the cursor to the upper left corner of the current clipping region. Same as _goto_home. _GOLEFT - (0x8C) Go to left margin. Moves the cursor to the left-most column of the current clipping region. Same as _goto_left. _GORIGHT - (0x8D) Go to right margin. Moves the cursor to the right-most column of the current clipping region. Same as _goto_right. _GOTOP - (0x8E) Go to top margin. Moves the cursor to the top row of the current clipping region. Same as _goto_top. _GOX,xpos - (0x8F) Go to X position. Moves the cursor to a specified column. The left-most column in the current clipping region is column zero. Same as _goto_x. _GOY,ypos - (0x90) Go to Y position. Moves the cursor to a specified row. The top row in the current clipping region is row zero. Same as _goto_y. _GOXY,xpos,ypos - (0x91) Go to X,Y position. Moves the cursor to a specified row and column. The upper left corner of the current clipping region is position 0,0. Same as _goto_xy. _INSLINE - (0xFF,0x4E) Insert line. Inserts a blank line at the cursor in the current clipping region. The current line and all lines below it are scrolled down one line. Same as _ins_line. _PUTATTR,attr - (0xFF,0x4F) Put attribute. Sets the next attribute on the current line to the specified attribute and advances the cursor. Same as _cput_attr. _PUTNATTR,attr,count - (0xFF,0x50) Put attribute N times. Sets a specified number of attributes on the current line to the specified attribute and advances the cursor. Same as _cput_nattr. _PUTCHRI,char - (0x02) Put character. Puts a character to the display without interpreting it. Same as _cput_chri. (This code is an alias for _CHRI.) _PUTNCHRI,char,count - (0x92) Put character N times. Puts a character to the display a specified number of times without interpreting it. Same as _cput_nchri. (_REP should be used to display an interpreted character a specified number of times.) _PUTSTRI,string - (0x03) Put string. Puts a string to the display without interpreting it. Same as _cput_stri. (This code is an alias for _STRI.) _PUTSTRCI,width,string- (0x93) Put centered string. Puts a centered string to the display without interpreting it. The string is centered within a region starting at the current cursor position and extending width positions in the cursor advance direction. Same as _cput_strci. _PUTSTRJI,width,string- (0x94) Put justified string. Puts a right-justified string to the display without interpreting it. The string is justified within a region starting at the current cursor position and extending width positions in the cursor advance direction. Same as _cput_strji. _REGION,left,top,wid- (0x95) Set clipping region th,height coordinates. Specifies a new clipping region with an upper left corner at (left,top) and with a specified width and height. If the clipping region is currently disabled, it is NOT automatically enabled. Same as _set_region. _REGON - (0x96) Region on. Enables the current clipping region. This restricts console I/O output to the currently-defined clipping region. Cursor is moved to the upper left corner (0,0) of the clipping region. Same as _region_on. _REGOFF - (0x97) Region off. Disables the current clipping region. This effectively extends the clipping region to the entire window or screen. Cursor returns to position it occupied before clipping region was enabled. Same as _region_off. _RELXY,xdist,ydist - (0x98) Move cursor to relative X,Y position. Moves the cursor a specified distance relative to its current position. Same as _rel_xy. (Note: a distance of -1 must be specified using the _255 or _0xFF equates.) _RESETATTR - (0x99) Reset text attribute to default. Resets the current text attribute and attribute flags. The current text attribute is set to the default text attribute, and the text attribute flags are cleared. Same as _reset_attr. _SCRLDOWN,count - (0xFF,0x51) Scroll down. Scrolls the current clipping region down a specified number of lines. Same as _scroll_down. _SCRLUP,count - (0xFF,0x52) Scroll up. Scrolls the current clipping region up a specified number of lines. Same as _scroll_up. _VBATTR,attr - (0xFF,0x53) Set video border attribute. Sets the video border color to match the background color of a given text attribute. Same as _set_vbordattr. _VBCOLOR,color - (0xFF,0x54) Set video border color. Sets the video border color to a specified color. Same as _set_vborder. _VBON - (0xFF,0x55) Video border on. Turns the video border on if it is currently off. Same as _vborder_on. _VBOFF - (0xFF,0x56) Video border off. Turns the video border off if it is currently visible. Same as _vborder_off.As used above, xdist and ydist indicate a signed distance to move in columns and rows, with negative values denoting motion up and to the left and positive values denoting motion down and to the right, as supported by the _rel_xy function. start and end designate normalized starting and ending cursor scan lines (where 0 denotes the top of the character cell and 255 denotes the bottom) as supported by the _set_cursor function. attr denotes a text attribute in the format supported by_set_attr. aflags denotes attribute flags as supported by _set_attrflags. color denotes a foreground or background color as supported by _set_bkcolor. xpos and ypos denote origin 0 X and Y coordinates (column and row positions, respectively).
The following example demonstrates the power and flexibility of the console I/O script codes. This example fills the screen with a black on cyan background, then creates a centered box with light gray on blue attributes, then draws a border around the box with a centered heading at the top. All of this output is performed by a single call to _cput_script, as shown below:
#include "script.h"
#include "console.h"
...
_cput_script(_FILLREG _177 _BLACK_CYAN _REGION _20 _5 _40 _16 _REGON
_AFILLREG _LTGRAY_BLUE _ATTR _WHITE_BLUE "Õ" _REP _38 "Í"
_DIRDOWN "¸", _REP _16 "³" _DIRLEFT "¾" _REP _38 "Í"
_DIRUP "Ô" _REP _16 "³" _DIRRIGHT _PUTSTRCI _40 __Arg_P
_GOXY _1 _1,"Current Stock Quotes");
...
/* define 40x16 centered box */
/* enable clipping region (box) */
/* fill box with ltgray on blue */
/* border is white on blue */
/* draw top border */
/* set direction DOWN */
/* draw right border */
/* set direction LEFT */
/* draw bottom border */
/* set direction UP */
/* draw left border */
/* right direction RIGHT */
/* display centered string */
/* position inside border */
...
Script code, arg(s) Parameter listDescription
__GETATBL char * (0xFF,0x60) (0xFF,0x61) __GETATBL_P char * * (0xFD,0xFF,0x61) __GETATBL_N char * near * (0xFE,0xFF,0x61) Get attribute __GETATBL_F char * far * table address. Saves the current attribute table address. (__GETATBL can only be used with the _v..._script functions.) __SETATBL char * (0xFF,0x62) (0xFF,0x63) __SETATBL_P char * * (0xFD,0xFF,0x63) __SETATBL_N char * near * (FEh,FFh,63h) Set attribute table __SETATBL_F char * far * address. Sets the attribute table address to a saved or specified value. Same as _set_attrtbl. __GETATTR char (0x9C) (0x9D) (0xFD,0x9D) __GETATTR_P char * (0xFE,0x9D) Get __GETATTR_N char near * text attribute. Saves the current __GETATTR_F char far * text attribute. (__GETATTR can only be used with the _v..._script functions.) Same as _get_attr. __SETATTR char (0x9E) (0x9F) (0xFD,0x9F) __SETATTR_P char * (0xFE,0x9F) Set __SETATTR_N char near * text attribute. Sets the text __SETATTR_F char far * attribute to a saved or specified value. Same as _set_attr. __GETATTRF char (0xA0) (0xA1) (0xFD,0xA1) __GETATTRF_P char * (0xFE,0xA1) Get __GETATTRF_N char near * attribute flags. Saves the current __GETATTRF_F char far * text attribute flags. (__GETATTRF can only be used with the _v..._script functions.) Same as _get_attrflags. __SETATTRF char (0xA2) (0xA3) (0xFD,0xA3) __SETATTRF_P char * (0xFE,0xA3) Set __SETATTRF_N char near * attribute flags. Sets the text __SETATTRF_F char far * attribute flags to a saved or specified value. Same as _set_attrflags. __GETBKBOLDM char 90xFF,0x64) (0xFF,0x65) __GETBKBOLDM_P char * (0xFD,0xFF,0x65) __GETBKBOLDM_N char near * (0xFE,0xFF,0x65) Get BKBOLD mode. __GETBKBOLDM_F char far * Saves the current blink/ background bold mode setting for the active display adapter. (The saved value is 1 if BKBOLD is currently supported, 0 otherwise.) (__GETBKBOLDM can only be used with the _v..._script functions.) __SETBKBOLDM char (0xFF,0x66) (0xFF,0x67) __SETBKBOLDM_P char * (0xFD,0xFF,0x67) __SETBKBOLDM_N char near * (0xFE,0xFF,0x67) Set BKBOLD mode. __SETBKBOLDM_F char far * Sets blink/ background bold mode for the active display adapter to a saved or specified setting. (The value must be 1 if BKBOLD is to be supported, 0 otherwise.) __GETCURSOR char [4] (0xA4) (0xA5) (0xFD,0xA5) __GETCURSOR_P char * [4] (0xFE,0xA5) Get __GETCURSOR_N char near * cursor shape and state. Saves the __GETCURSOR_F [4] current cursor char far * shape and on/off state. The [4] argument is expected to point to a 4-byte array. The first two bytes contain the cursor shape in the same format supported by _get_cursor. The third byte is 1 if the cursor is on, 0 otherwise. The last byte is reserved. (__GETCURSOR can only be used with the _v..._script functions.) Same as _get_cursor. __SETCURSOR char [4] (0xA6) (0xA7) (0xFD,0xA7) __SETCURSOR_P char * [4] (0xFE,0xA7) Set __SETCURSOR_N char near * cursor shape and state. Sets the __SETCURSOR_F [4] cursor to a char far * [4]saved or specified shape and state. The argument is expected to be a 4-byte array or a pointer to a 4-byte array. The first two bytes must contain the cursor shape in the same format supported by _set_cursor. The third byte is 1 if the cursor is to be turned on, 0 otherwise. The last byte is reserved. __GETDATTR char (0xFF,0x68) (0xFF,0x69) __GETDATTR_P char * (0xFD,0xFF,0x69) __GETDATTR_N char near * (0xFE,0xFF,0x69) Get default __GETDATTR_F char far * attribute. Saves the current default attribute. (__GETDATTR can only be used with the _v..._script functions.) Same as _get_dattr. __SETDATTR char (0xFF,0x6A) (0xFF,0x6B) __SETDATTR_P char * (0xFD,0xFF,0x6B) __SETDATTR_N char near * (0xFE,0xFF,0x6B) Set default __SETDATTR_F char far * attribute. Sets the default attribute to a saved or specified value. Same as _set_dattr. __GETDIREC int (0xFF,0x6C) (0xFF,0x6D) __GETDIREC_P int * (0xFD,0xFF,0x6D) __GETDIREC_N int near * (0xFE,0xFF,0x6Fh) Get cursor __GETDIREC_F int far * advance direction. Saves the current cursor advance direction. (__GETDIREC can only be used with the _v..._script functions.) Same as _get_direction. __SETDIREC int (0xFF,0x6E) (0xFF,0x6F) __SETDIREC_P int * (0xFD,0xFF,0x6F) __SETDIREC_N int near * (0xFE,0xFF,0x6F) Set cursor advance __SETDIREC_F int far * direction. Sets the cursor advance direction to a saved or specified value. Same as _set_direction. __GETREGION char [6] (0xA8) (0xA9) (0xFD,0xA9) __GETREGION_P char * [6] (0xFE,0xA9) Get __GETREGION_N char near * clipping region coordinates and __GETREGION_F [6] state. Saves the char far * current clipping region coordinates [6] and on/off state. The argument is expected to be a pointer to a 6-byte array. The first four bytes contain the coordinates (top, left, width, height). The fifth byte is 1 if the clipping region is enabled, 0 otherwise. The last byte is reserved. (__GETREGION can only be used with the _v..._script functions.) __SETREGION char [6] (0xAA) (0xAB) (0xFD,0xAB) __SETREGION_P char * [6] (0xFE,0xAB) Set __SETREGION_N char near * clipping region coordinates and __SETREGION_F [6] state. Sets the char far * [6]clipping region coordinates and on/off state to a saved or specified value. The argument is expected to be a 6-byte array or a pointer to a 6-byte array. The first four bytes must contain the coordinates (top, left, width, height). The fifth byte must be 1 if the clipping region is to be enabled, 0 otherwise. The last byte is reserved. __GETVBORDER int (0xFF,0x70) (0xFF,0x71) __GETVBORDER_P int * (0xFD,0xFF,0x71) __GETVBORDER_N int near * (0xFE,0xFF,0x71) Get video border __GETVBORDER_F int far * color and state. Saves the current video border color and video border on/off state. The border color is saved in the low (first) byte of the int value. The last byte is 1 if the video border is enabled, 0 otherwise. (__GETVBORDER can only be used with the _v..._script functions.) __SETVBORDER int (0xFF,0x72) (0xFF,0x73) __SETVBORDER_P int * (0xFD,0xFF,0x73) __SETVBORDER_N int near * (0xFE,0xFF,0x73) Set video border __SETVBORDER_F int far * color and state. Sets the video border color and video border on/off state to a saved or specified value. The border color must occupy the low (first) byte of the int value. The last byte must be 1 if the video border is to be enabled, 0 otherwise. __GETX char (0xFF,0x74) (0xFF,0x75) __GETX_P char * (0xFD,0xFF,0x75) __GETX_N char near * (0xFE,0xFF,0x75) Get X position. __GETX_F char far * Saves the current cursor column position. (__GETX can only be used with the _v..._script functions.) Same as _where_x. __SETX char (0xFF,0x76) (0xFF,0x77) __SETX_P char * (0xFD,0xFF,0x77) __SETX_N char near * (0xFE,0xFF,0x77) Set X position. __SETX_F char far * Moves the cursor to a saved or specified column position. Same as _goto_x. __GETY char (0xFF,0x78) (0xFF,0x79) __GETY_P char * (0xFD,0xFF,0x79) __GETY_N char near * (0xFE,0xFF,0x79) Get Y position. __GETY_F char far * Saves the current cursor row position. (__GETY can only be used with the _v..._script functions.) Same as _where_y. __SETY char (0xFF,0x7A) (0xFF,0x7B) __SETY_P char * (0xFD,0xFF,0x7B) __SETY_N char near * (0xFE,0xFF,0x7B) Set Y position. __SETY_F char far * Moves the cursor to a saved or specified row position. Same as _goto_y. __GETXY int (0xAC) (0xAD) (0xFD,0xAD) __GETXY_P int * (0xFE,0xAD) __GETXY_N int near * Get X,Y position. Saves the current __GETXY_F int far * cursor position. The X position is saved in the low (first) byte of the int value. (__GETXY can only be used with the _v..._script functions.) Same as _where_xy. __SETXY int (0xAE) (0xAF) (0xFD,0xAF) __SETXY_P int * (0xFE,0xAF) Set __SETXY_N int near * X,Y position. Moves the cursor to a __SETXY_F int far * saved or specified position. The X position must occupy the low (first) byte of the int value. Same as _goto_xy.Numbers in brackets ([4], [6]) indicate the size of the character array, in bytes.
The __GET...P codes are used most often in situations where the programmer does not have access to the parameter list, as in a C or C++ environment (using the _?put_script and _?get_script functions). The __GET... codes without suffixes (e.g., __GETATBL, __GETXY) are useful with the _v?put_script and _v?get_script functions, since they store the returned value in the next position in the parameter list, where it would be expected if it were being read from the parameter list. This allows saved values to be stored in the same script from which they will be restored, as in the following example:
#include "script.h"
...
int paramlist[] = {0,0,23};
_vcput_script(__GETXY __GETATTRF _GOBOTTOM _GOLEFT "Backup time remaining: "
_BOLDON __CHAR _Nolimit _Default " minutes" _CLREOL, paramlist);
/* save cursor position */
/* save attribute flags */
/* move to left,bottom */
/* display bold message */
/* force BOLD */
/* clear rest of line */
...
_vcput_script(__SETXY __SETATTRF, paramlist);
/* restore cursor, attr flags - using same parameter list */
...
This particular script produces the following output on the bottom line of the display:
Backup time remaining: 23 minutes
Note that this script does not disturb the cursor position or attribute flags. This makes it ideal for use by a background task (e.g., using the multitasking system) since it will not affect the behavior of other tasks which may also be using the console I/O system.
Script code, arg(s) Parameter listDescription
_USER - (0x7F,ANY) Reserved for user extensions to the scripting language.All other unassigned codes are reserved for use in future releases of Spontaneous Assembly.
If you are not using all of the scripted I/O codes in your application, chances are good that you can significantly reduce the size of the scripted I/O system by following the simple steps outlined below. Because the optimization is performed at the assembly language level, you will need an assembler. The optimization is accomplished as follows: