Scripted I/O

Reference Section

_cget_script
_cput_script
_get_script
_hget_script
_hput_script
_put_script
_sget_script
sio_addr
_sput_script
_vcget_script
_vcput_script
_vget_script
_vhget_script
_vhput_script
_vput_script
_vsget_script
_vsput_script

_cget_script


Descrip
Reads and interprets console I/O keyboard input using an input script.

Syntax
#include <script.h>
int _cget_script(int count, const char *inscript[,paramlist,...]);
Returns
0 if the keyboard was successfully read using the input script.
s_status final script status (error code is SE_OK)

1 if end-of-input was encountered before the input script could be fully processed.
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads keyboard data into a temporary buffer using the _cget_str function or its equivalent and interprets the input string as specified in the input script (inscript). No more than count characters or a single line of text (whichever is encountered first) is read and echoed to the display. The input data is interpreted as specified in inscript and the resulting values are stored as specified by the parameter list (paramlist). 0 is returned if the script was successfully processed. 1 is returned if end-of-input was encountered before inscript could be fully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Keyboard input is always processed sequentially, a character at a time, beginning with the first keyboard input character, as specified in inscript. Under no condition is more than one line of keyboard input read to satisfy the script.

Technically, a return value of 1 indicates an error return. However, the programmer must determine if this condition is a true error. Since end-of-input is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-input was encountered.

_console_init must be called before using this function.

External parameters to inscript are specified as individual arguments following inscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

Script Code Summary

The following tables summarize the input script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffix Type of parameter expected on parameter list

None Immediate value (pointer if a string or structure is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ character or code
Repeat the next
count times

_CHRI,char _ Match char without
interpreting it

_STRI,string _ Match string without
interpreting it

_SCRIPT,script _ Process script as an
embedded script

__CALL... paramlist * Call a new script
script *, and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any Skip the next
parameter in the
parameter list

Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record

_TOFIELD _ Advance to next
field

_TOSPACE _ Skip to next space
or TAB

_TOCHR,char _ Advance past next
occurrence of char

_TOSTR,string _ Advance past next
occurrence of string

_TOSET,charset _ Advance past next
occurrence of any
character in charset

_SKPCNT,count _ Skip the next count
characters

_SKPSPACE _ Skip an optional
space or TAB
character

_SKPCHR,char _ Skip an optional
char

_SKPSTR,string _ Skip an optional
occurrence of string

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset

_SKPSPACES _ Skip all consecutive
space or TAB
characters

_SKPCHRS,char _ Skip all consecutive
occurrences of char

_SKPSTRS,string _ Skip all consecutive
occurrences of
string

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset

_REQSPACE _ Skip a required
space or TAB

_REQCHR,char _ Skip a required
occurrence of char

_REQSTR,string _ Skip a required
occurrence of string

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset

Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width,radix,align char Output a formatted
char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width,radix,align long Output a formatted
long in a specified
radix

__ASCQUAD...,width,radix,align quad Output a formatted
quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width,
dformat,sformat long date Output a formatted
long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string

Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with a NULL. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively. These options are flexibly interpreted in input scripts to facilitate reading of formatted values without unnecessarily constraining the input format. For example, if an unaligned value is written, it may be read using any input alignment type.

The following alignment options apply to nformat, sformat, and align:

_Noalign (0x00) No leading or trailing pad characters are skipped
_Lalign (0x80) Trailing pad characters are skipped
_Ralign (0x40) Leading pad characters are skipped
_Calign (0xC0) Leading and trailing pad characters are skipped

The following options apply to nformat ONLY:

_Noplus (0x00) Do not allow plus sign
_Plus (0x10) Allow plus sign for positive values
_Nocurrency (0x00) Do not allow currency format
_Currency (0x08) Allow currency format
_Nothous (0x00) Do not allow thousands separators
_Thous (0x04) Allow thousands separators
_Noexp (0x00) Do not allow exponential format (ignores exponent if present)
_Exp (0x01) Allow exponential format (reads exponent if present)
_Flex (0x02) Allow exponential format (reads exponent if present)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on input
_Lower (0x02) Convert ASCII characters to lowercase on input

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following input options apply to dformat (options which are not listed are ignored):

_Cntrydate (0x00) Read date using country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Read date using DAY/MONTH/YEAR order
_Ymd (0x02) Read date using YEAR/MONTH/DAY order
_Mdy (0x03) Read date using MONTH/DAY/YEAR order
_Noyr (0x04) No YEAR (suppresses YEAR in the date string if present)
_Nomon (0x08) No MONTH (suppresses MONTH in the date string if present)
_Noday (0x10) No DAY (suppresses DAY in the date string if present)

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order. For example: _Mdy, _Ymd_Noday, _Cntrydate_Noday_Nomon.

tformat specifies the output time format. The following input options apply to tformat (options which are not listed are ignored):

_Flexhr (0x00) Read time in either 12-hour or 24-hour format, as encountered
_12hr (0x01) Read time in 12-hour format with trailing am/pm strings
_24hr (0x02) Read time in 24-hour format
_Cntryhr (0x03) Read time in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) No HOUR (suppresses HOUR in the time string if present)
_Nomin (0x08) No MINUTES (suppresses MINUTES in the time string if present)
_Nosec (0x10) No SECONDS (suppresses SECONDS in the time string if present)
_No100ths (0x20) No 100THS (suppresses 100THS in the time string if present)

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths, _Nosec_No100ths.

precision specifies the number of digits to be read to the right of the decimal point. Excess digits are skipped (up to the limit imposed by width). precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following input options may be combined with precision (options which are not listed are ignored):

_Fill (0x40) Pad characters after the fractional portion are skipped (up to precision total characters)
_Round (0x00) Round the final significant digit of the input value if more digits are present
_Trunc (0x20) Truncate the final significant digit of the input value if more digits are present

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Fill, _10_Fill_Trunc.

width specifies the maximum width of the input field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be processed for a specific value. If field overflow characters are encountered when reading a value, an error is returned (if field overflow checking is enabled) or the read is simply skipped (if field overflow checking is not enabled). A width of zero (_Nolimit) is the same as the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.
WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

The examples below read two float values from the keyboard (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	{
	   float xloc, yloc;

	   _cput_str("\n\rInput X,Y coordinates: ");
	   _cget_script(126,__FLOAT_P _Nolimit _2 _Calign _SKPCHR ","
	                __FLOAT_P _Nolimit _2 _Calign, &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char msg[] = "\n\rInput X,Y coordinates: ";   
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	        _SKPCHR ","
	   	        __FLOAT_P _Nolimit _2 _Calign_Exp;
	   float xloc, yloc;
	   float *xy_params[2];

	   pushss
	   pop es	 	/* ES=SS (param list on stack) */
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load param list w/pointers */
	xy_read:
	   lea si,msg	/* SI = offset of message */
	   cput_str();	/* display message */
	   lea si,xy_script/* SI = offset of script */
	   lea di,xy_params/* DI = offset of param list */
	   mov cx,126	/* CX = maximum chars to read */
	   cget_script();     /* read x,y coordinates */
	    je ok
	    ja again
	   jmp xy_read	    /* error, invalid input */
	again:	  	 	/* error, insufficient input */
	   jmp xy_read	
	ok:	  	 	/* successful, continue */
	   ...
	}

Source file _SIOCGET.ASM ASM equivâ
See also
_cput_script, _cget_s, _get_script, _hget_script, _sget_script, _vcget_script, sio_addr

_cput_script


Descrip
Uses an output script to write data to the display (console I/O system).

Syntax
#include <script.h>
int _cput_script(const char *outscript[,paramlist,...]);

Returns
0 if the output script was successfully processed.
s_status final script status (error code is SE_OK)

-1 if an error occurred.
s_status final script status (error code indicates exact error)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to the current display using the console I/O system. 0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Output data is written to the display starting at cursor position and continuing in the cursor advance direction. The cursor is advanced past each character written. Output is restricted to the clipping region if the clipping region is enabled; otherwise, it is restricted to the active screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

outscript may include console I/O control codes to change console I/O system options as the script is processed, including current display attribute, cursor advance direction, clipping region, etc. Such changes remain in effect after the script has been processed.

_console_init must be called before using this function.

External parameters to outscript are specified as individual arguments following outscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x20-0x7E and 0xB0-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x1F, 0x7F-0xAF, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function supports the full console I/O code set.

Script Code Summary

The following tables summarize the output script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffix Type of parameter expected on parameter list

None Immediate value (pointer if a string is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times

_CHRI,char _ Process char without
interpretation

_STRI,string _ Process string
without interpretation

_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist * and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any Skip the next
parameter in the
parameter list

Console I/O Codes

Script code, arg(s) Parameter list Description

_BEL _ Beep

_BS _ Backspace

_LF _ Line feed

_CR _ Carriage return

_TAB _ Tab
_NL _ Newline

_FF _ Form feed (clear
screen or clipping
region)

_DOWN _ Move cursor down one
row

_LEFT _ Move cursor left one
column

_NEXT _ Move cursor to next
cursor position

_RIGHT _ Move cursor right
one column

_UP _ Move cursor up one
row

_AFILLEOL,attr _ Attribute fill to
end of line

_AFILLINE,attr _ Attribute fill line

_AFILLN,attr,count _ Attribute fill N
positions

_AFILLREG,attr _ Attribute fill
region

_ATTR,attr _ Set text attribute

_ATTRF,aflags _ Set attribute flags

_BKBOLDM _ Set background bold
mode

_BKBOLDON _ Background bold on

_BKBOLDOFF _ Background bold off

_BKCOLOR,color _ Set background color

_BLINKM _ Set blink mode

_BLINKON _ Blink on

_BLINKOFF _ Blink off

_BOLDON _ Bold on

_BOLDOFF _ Bold off

_CLREOL _ Clear to end of line

_CLRLINE _ Clear line

_CLRN,count _ Clear N positions

_CLRREG _ Clear region

_CURSON _ Cursor on

_CURSOFF _ Cursor off

_CURSOR,end,start _ Set cursor shape

_DATTR,attr _ Set default
attribute

_DELLINE _ Delete line

_DIRECTION,xdist,ydist _ Set cursor advance
direction

_DIRDOWN _ Advance down

_DIRLEFT _ Advance left

_DIRRIGHT _ Advance right

_DIRUP _ Advance up

_FGCOLOR,color _ Set foreground color

_FILLEOL,char,attr _ Fill to end of line

_FILLINE,char,attr _ Fill line

_FILLN,char,attr,count _ Fill N positions

_FILLREG,char,attr _ Fill region

_GOBOTTOM _ Go to bottom margin

_GOEND _ Go to end (bottom
right corner)

_GOHOME _ Go to home (top left
corner)

_GOLEFT _ Go to left margin

_GORIGHT _ Go to right margin

_GOTOP _ Go to top margin

_GOX,xpos _ Go to X position

_GOY,ypos _ Go to Y position

_GOXY,xpos,ypos _ Go to X,Y position

_INSLINE _ Insert line

_PUTATTR,attr _ Put attribute

_PUTNATTR,attr,count _ Put attribute N
times

_PUTCHRI,char _ Put character
without interpreting
it

_PUTNCHRI,char,count _ Put character N
times without
interpreting it

_PUTSTRI,string _ Put string without
interpreting it

_PUTSTRCI,width,string _ Put centered string
without interpreting
it

_PUTSTRJI,width,string _ Put right-justified
string without
interpreting it

_REGON _ Region on

_REGOFF _ Region off

_RELXY,xdist,ydist _ Move cursor to
relative X,Y
position

_RESETATTR _ Reset text attribute
to default

_SCRLDOWN,count _ Scroll down

_SCRLUP,count _ Scroll up

_REGION,left,top,width,height _ Set clipping region
coordinates

_VBATTR,attr _ Set video border
attribute

_VBCOLOR,color _ Set video border
color

_VBON _ Video border on

_VBOFF _ Video border off

__GETATBL... char * [*] Get attribute table
address

__SETATBL... char * [*] Set attribute table
address

__GETATTR... char Get text attribute

__SETATTR... char Set text attribute

__GETATTRF... char Get attribute flags

__SETATTRF... char Set attribute flags

__GETBKBOLDM... char Get BKBOLD mode

__SETBKBOLDM... char Set BKBOLD mode

__GETCURSOR... char * (4 bytes) Get cursor shape and
state

__SETCURSOR... char * (4 bytes) Set cursor shape and
state

__GETDATTR... char Get default
attribute

__SETDATTR... char Set default
attribute

__GETDIREC... int Get cursor advance
direction

__SETDIREC... int Set cursor advance
direction

__GETREGION... char * (6 bytes) Get clipping region
coordinates and
state

__SETREGION... char * (6 bytes) Set clipping region
coordinates and
state

__GETVBORDER... int Get video border
color and state

__SETVBORDER... int Set video border
color and state

__GETX... char Get X position

__SETX... char Set X position

__GETY... char Get Y position

__SETY... char Set Y position

__GETXY... int Get X,Y position

__SETXY... int Set X,Y position


Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record (writes a
record delimiter)

_TOFIELD _ Advance to next
field (writes a
field delimiter)

_TOSPACE _ Skip to next space
or TAB (writes a
space character)

_TOCHR,char _ Advance past next
occurrence of char
(writes char)

_TOSTR,string _ Advance past next
occurrence of string
(writes string)

_TOSET,charset _ Advance past next
occurrence of any
character in charset
(writes the first
character in
charset)

_SKPCNT,count _ Skip the next count
characters (writes
count space
characters)

_SKPSPACE _ Skip an optional
space or TAB
character (writes a
space character)
_SKPCHR,char _ Skip an optional
char (writes char)

_SKPSTR,string _ Skip an optional
occurrence of string
(writes string)

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset (writes the
first character in
charset)

_SKPSPACES _ Skip all consecutive
space or TAB
characters (writes a
space character)

_SKPCHRS,char _ Skip all consecutive
occurrences of char
(writes char)

_SKPSTRS,string _ Skip all consecutive
occurrences of
string (writes
string)

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset
(writes the first
character in
charset)

_REQSPACE _ Skip a required
space or TAB (writes
a space character)

_REQCHR,char _ Skip a required
occurrence of char
(writes char)

_REQSTR,string _ Skip a required
occurrence of string
(writes string)

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset (writes the
first character in
charset)


Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int
__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width, char Output a formatted
radix,align char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
radix,align radix
quad in a specified

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char ASCII character
Output a formatted

__STRING...,width,sformat char * Output a formatted
ASCII string

Refer to the Integer Math technical notes for the bcd, bcdptr, quad and quadptr types and typedefs.

Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with an NULL character. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively.

The following options apply to nformat, sformat, and align:

_Noalign (0x00) Result is not aligned
_Lalign (0x80) Result is left-aligned
_Ralign (0x40) Result is right-aligned
_Calign (0xC0) Result is center-aligned
_Zalign (0x20) The result is right-aligned using leading zeros

The following options apply to nformat ONLY:

_Noplus (0x00) Suppress plus sign if positive
_Plus (0x10) Force plus sign if positive
_Nocurrency (0x00) Do not output in currency format
_Currency (0x08) Output in currency format
_Nothous (0x00) Do not output thousands separators
_Thous (0x04) Output using thousands separators
_Noexp (0x00) Output in non-exponential format
_Exp (0x01) Output in exponential format
_Flex (0x02) Output in "flex" format (non-exponential if possible)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on output
_Lower (0x02) Convert ASCII characters to lowercase on output

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following options apply to dformat:

_Cntrydate (0x00) Use country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Force DAY/MONTH/YEAR order
_Ymd (0x02) Force YEAR/MONTH/DAY order
_Mdy (0x03) Force MONTH/DAY/YEAR order
_Noyr (0x04) Suppress YEAR in the date string
_Nomon (0x08) Suppress MONTH in the date string
_Noday (0x10) Suppress DAY in the date string
_Padmon (0x00) Pad the MONTH field with a leading zero, if required
_Nopadmon (0x20) Do not zero pad the MONTH field
_Padday (0x00) Pad the DAY field with a leading zero, if required
_Nopadday (0x40) Do not zero pad the DAY field
_2digyr (0x00) Output the YEAR as a 2-digit number
_4digyr (0x80) Output the YEAR as a 4-digit number

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order, followed by pad options in alphabetical order, followed by the year format option. Default options (value equal to 0x00) may be omitted; _Padmon and _Padday are defaults and are always omitted. For example: _Mdy, _Ymd_Noday_Nopadmon_4digyr, _Ymd_Nopadday_Nopadmon_4digyr, _Dmy_4digyr.

tformat specifies the output time format. The following options apply to tformat:

_Flexhr (0x00) Output in country-specified time format (12-hour or 24-hour)
_12hr (0x01) Force 12-hour time format with trailing am/pm strings
_24hr (0x02) Force 24-hour time format
_Cntryhr (0x03) Output in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) Suppress the HOUR field in the time string
_Nomin (0x08) Suppress the MINUTES field in the time string
_Nosec (0x10) Suppress the SECONDS field in the time string
_No100ths (0x20) Suppress the 100THS of seconds field in the time string
_Padtime (0x00) Pad the left-most time field with a leading zero, if required
_Nopadtime (0x40) Do not zero pad the left-most time field

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance, followed by pad options in alphabetical order. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths_Nopadtime.

precision specifies the number of digits to the right of the decimal point. precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision
In addition, the following options may be combined with precision:

_Fix (0x00) Pad right with zeros to force precision digits to the right of the decimal point
_Float (0x80) Do not pad digits to the right of the decimal point, if necessary
_Fill (0x40) Pad right with pad characters to force precision digits to the right of the decimal point
_Round (0x00) Round the final significant digit of the result, if required
_Trunc (0x20) Truncate the final significant digit of the result, if required

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Float, _10_Fix_Trunc.

width specifies the maximum width of the output field, in characters. width must be a value in the range 0..126. Under no condition will more than width characters be output for any value. If the formatted value would exceed width, an error is returned (if field overflow checking is enabled) or the field is filled with overflow characters (if field overflow checking is disabled). Specifying a width of zero (_Nolimit) is the same as specifying the maximum supported width (at least 126 characters):

Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

C/C++ Example
	{
	   float xloc = 12.70, yloc = -34.0;
	   ...
	   _cput_script("\n\rX co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	  _Ralign	_REP _12 " "
	   	  "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	  _Ralign, &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   float xloc = 12.70, yloc = -34.0;
	   float *xy_params[2];
	   char xy_script[] = "\n\rX co-ordinate: "__FLOAT_P _8 _2_Fix
	   	        _Ralign _REP _12 " "
	   	        "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	        _Ralign;
	   ... 
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load param list w/ptrs */
	   pushss
	   pop es	 	/* ES = SS (param on stack) */
	   lea si,xy_script/* DS:SI -> script string */
	   lea di,xy_params/* ES:DI -> parameter list */
	   cput_script();	/* display x,y coordinates */
	   ...
	}

Source file _SIOCPUT.ASM ASM equivâ
See also
_cget_s, _cput_str, _hput_script, _put_script, _sput_script, sio_addr, _vcput_script

_get_script


Descrip
Reads and interprets input from STDIN using an input script.

Syntax
#include <script.h>
int _get_script(unsigned int count, const char *inscript[,paramlist,...]);

Returns
0 if the input was successfully read using the input script.
s_status final script status (error code is SE_OK)

1 if end-of-input was encountered before the input script could be fully processed.
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
s_status final script status (error code indicates error type)
Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads keyboard data into a temporary buffer using the _get_str function or its equivalent and interprets the input string as specified in the input script (inscript). No more than count characters or a single line of text is read (whichever is encountered first). Characters are echoed to the screen unless STDIN has been redirected. The input data is interpreted as specified in inscript and the resulting values are stored as specified by the parameter list (paramlist). 0 is returned if the script was successfully processed. 1 is returned if end-of-
input was encountered before inscript could be fully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Input from STDIN is always processed sequentially, a character at a time, beginning with the first input character, as specified in inscript. Under no condition is more than one line or more than count characters read from STDIN to satisfy the script.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-input is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-input was encountered.

External parameters to inscript are specified as individual arguments following inscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be the default data segment (where global and static data are located). The near pointer override cannot be used 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

Script Code Summary

The following tables summarize the input script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffixType of parameter expected on parameter list

None Immediate value (pointer if a string or structure is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times

_CHRI,char _ Match char without
interpreting it

_STRI,string _ Match string without
interpreting it

_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist and/or parameter
* list

__CHAIN... script *, Chain to a new
paramlist script and/or
* parameter list

__SKPPARAM,size any Skip the next
parameter in the
parameter list

Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record

_TOFIELD _ Advance to next
field

_TOSPACE _ Skip to next space
or TAB
_TOCHR,char _ Advance past next
occurrence of char

_TOSTR,string _ Advance past next
occurrence of string

_TOSET,charset _ Advance past next
occurrence of any
character in charset

_SKPCNT,count _ Skip the next count
characters

_SKPSPACE _ Skip an optional
space or TAB
character

_SKPCHR,char _ Skip an optional
char

_SKPSTR,string _ Skip an optional
occurrence of string

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset

_SKPSPACES _ Skip all consecutive
space or TAB
characters

_SKPCHRS,char _ Skip all consecutive
occurrences of char

_SKPSTRS,string _ Skip all consecutive
occurrences of
string

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset

_REQSPACE _ Skip a required
space or TAB

_REQCHR,char _ Skip a required
occurrence of char

_REQSTR,string _ Skip a required
occurrence of string

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset

Formatted Data Conversion Codes

_UNSIGNED _ fixed-point value is
Next integer or
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad quad
Output a formatted

__ASCCHAR...,width,radix,align char Output a formatted
char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width,radix,align long Output a formatted
long in a specified
radix

__ASCQUAD...,width,radix,align quad Output a formatted
quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char ASCII character
Output a formatted

__STRING...,width,sformat char * Output a formatted
ASCII string

Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with a NULL. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively. These options are flexibly interpreted in input scripts to facilitate reading of formatted values without unnecessarily constraining the input format. For example, if an unaligned value is written, it may be read using any input alignment type.

The following options apply to nformat, sformat, and align:

_Noalign (0x00) No leading or trailing pad characters are skipped
_Lalign (0x80) Trailing pad characters are skipped
_Ralign (0x40) Leading pad characters are skipped
_Calign (0xC0) Leading and trailing pad characters are skipped

The following options apply to nformat ONLY:

_Noplus (0x00) Do not allow plus sign
_Plus (0x10) Allow plus sign for positive values
_Nocurrency (0x00) Do not allow currency format
_Currency (0x08) Allow currency format
_Nothous (0x00) Do not allow thousands separators
_Thous (0x04) Allow thousands separators
_Noexp (0x00) Do not allow exponential format (ignores exponent if present)
_Exp (0x01) Allow exponential format (reads exponent if present)
_Flex (0x02) Allow exponential format (reads exponent if present)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on input
_Lower (0x02) Convert ASCII characters to lowercase on input

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.
dformat specifies the output date format. The following input options apply to dformat (options which are not listed are ignored):

_Cntrydate (0x00) Read date using country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Read date using DAY/MONTH/YEAR order
_Ymd (0x02) Read date using YEAR/MONTH/DAY order
_Mdy (0x03) Read date using MONTH/DAY/YEAR order
_Noyr (0x04) No YEAR (suppresses YEAR in the date string if present)
_Nomon (0x08) No MONTH (suppresses MONTH in the date string if present)
_Noday (0x10) No DAY (suppresses DAY in the date string if present)

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order. For example: _Mdy, _Ymd_Noday, _Cntrydate_Noday_Nomon.

tformat specifies the output time format. The following input options apply to tformat (options which are not listed are ignored):

_Flexhr (0x00) Read time in either 12-hour or 24-hour format, as encountered
_12hr (0x01) Read time in 12-hour format with trailing am/pm strings
_24hr (0x02) Read time in 24-hour format
_Cntryhr (0x03) Read time in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) No HOUR (suppresses HOUR in the time string if present)
_Nomin (0x08) No MINUTES (suppresses MINUTES in the time string if present)
_Nosec (0x10) No SECONDS (suppresses SECONDS in the time string if present)
_No100ths (0x20) No 100THS (suppresses 100THS in the time string if present)

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths, _Nosec_No100ths.

precision specifies the number of digits to be read to the right of the decimal point. However, if more digits are encountered they are skipped (up to the limit imposed by width). precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following input options may be combined with precision (options which are not listed are ignored):

_Fill (0x40) Pad characters after the fractional portion are skipped (up to precision total characters)
_Round (0x00) Round the final significant digit of the input value if more digits are present
_Trunc (0x20) Truncate the final significant digit of the input value if more digits are present

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Fill, _10_Fill_Trunc.

width specifies the maximum width of the input field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be processed for a specific value. If field overflow characters are encountered when reading a value, an error is returned (if field overflow checking is enabled) or the read is simply skipped (if field overflow checking is not enabled). A width of zero (_Nolimit) is the same as the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

The following input script reads two float values from the keyboard (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	{
	   float xloc, yloc;
	   ...
	   _put_str("\n\rInput X,Y coordinates: ");
	   _get_script(__FLOAT_P _Nolimit _2 _Calign_Exp _SKPCHR ","
	         __FLOAT_P _Nolimit _2 _Calign_Exp, &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include"inline.h"
	{
	   char str[] = "\n\rInput X,Y coordinates: ";
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	     _SKPCHR ","
	   	     __FLOAT_P _Nolimit _2 _Calign_Exp;
	   float xloc, yloc;
	   float *xy_params[2];
	   ...   
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load list w/ptrs */
	xy_read:
	   lea si,str	/* SI -> message */
	   put_str();
	   lea si,xy_script /* SI -> script string */
	   lea di,xy_params /* DI -> parameter list */
	   mov cx,126	/* CX = max num of input chars */
	   get_script();      /* read x,y coordinates */
	    je ok
	    ja again
	   jmp xy_read	    /* error, invalid input */

	again:	  	 	/* error, insufficient input */
	   jmp xy_read	

	ok:	  	 	/* successful, continue */
	   ...
	}

Source file _SIODGET.ASM ASM equiv GET_SCRIPT
See also
_cget_s, _get_str, _hget_script, put_script, _sget_script, sio_addr, _vget_script

_hget_script


Descrip
Reads and interprets input from a file or device using an input script.

Syntax
#include <script.h>
int _hget_script (int handle, int *count, const char *inscript[,paramlist,...]);

Returns
0 if the input was successfully read using the input script.
count number of characters read from handle
s_status final script status (error code is SE_OK)

1 if end-of-file was encountered before the input script could be fully processed.
count number of characters read from handle
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
count number of characters read from handle
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads ASCII data into a temporary buffer from the file or device associated with handle and interprets that data as specified in the input script (inscript). As values are read from the input data, they are stored as specified by the parameter list (paramlist). 0 is returned if the script was successfully processed. 1 is returned if end-of-file was encountered before inscript could be fully processed. -1 is returned if an error occurred. count always indicates the number of characters actually read. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Input data is always processed sequentially, a character at a time. If handle is associated with a file, then input data is read starting at the current file pointer position. On return, the file pointer points past the last character actually processed or interpreted by the input script (NOT the last character read). If handle is associated with a character device (e.g., CON), then data which is read from the device but not processed by the script is discarded. Note that multiple lines of input may be processed for a single input script if STDIN is specified as the input device.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-file is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-file was encountered.

External parameters to inscript are specified as individual arguments following inscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near pointer or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

Script Code Summary

The following tables summarize the input script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffix Type of parameter expected on parameter list

None Immediate value (pointer if a string or structure is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times

_CHRI,char _ Match char without
interpreting it

_STRI,string _ Match string without
interpreting it

_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist * and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any Skip the next
parameter list
parameter in the

Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record

_TOFIELD _ Advance to next
field

_TOSPACE _ Skip to next space
or TAB

_TOCHR,char _ Advance past next
occurrence of char

_TOSTR,string _ Advance past next
occurrence of string

_TOSET,charset _ Advance past next
occurrence of any
character in charset

_SKPCNT,count _ Skip the next count
characters

_SKPSPACE _ Skip an optional
space or TAB
character

_SKPCHR,char _ Skip an optional
char

_SKPSTR,string _ Skip an optional
occurrence of string

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset

_SKPSPACES _ Skip all consecutive
space or TAB
characters

_SKPCHRS,char _ Skip all consecutive
occurrences of char

_SKPSTRS,string _ Skip all consecutive
occurrences of
string

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset

_REQSPACE _ Skip a required
space or TAB

_REQCHR,char _ Skip a required
occurrence of char

_REQSTR,string _ Skip a required
occurrence of string

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset

Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width, char Output a formatted
radix,align char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
radix
int in a specified

__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, Output a formatted
precision,nformat float float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string


Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with a NULL. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively. These options are flexibly interpreted in input scripts to facilitate reading of formatted values without unnecessarily constraining the input format. For example, if an unaligned value is written, it may be read using any input alignment type.

The following options apply to nformat, sformat, and align:

_Noalign (0x00) No leading or trailing pad characters are skipped
_Lalign (0x80) Trailing pad characters are skipped
_Ralign (0x40) Leading pad characters are skipped
_Calign (0xC0) Leading and trailing pad characters are skipped

The following options apply to nformat ONLY:

_Noplus (0x00) Do not allow plus sign
_Plus (0x10) Allow plus sign for positive values
_Nocurrency (0x00) Do not allow currency format
_Currency (0x08) Allow currency format
_Nothous (0x00) Do not allow thousands separators
_Thous (0x04) Allow thousands separators
_Noexp (0x00) Do not allow exponential format (ignores exponent if present)
_Exp (0x01) Allow exponential format (reads exponent if present)
_Flex (0x02) Allow exponential format (reads exponent if present)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on input
_Lower (0x02) Convert ASCII characters to lowercase on input

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following input options apply to dformat (options which are not listed are ignored):

_Cntrydate (0x00) Read date using country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Read date using DAY/MONTH/YEAR order
_Ymd (0x02) Read date using YEAR/MONTH/DAY order
_Mdy (0x03) Read date using MONTH/DAY/YEAR order
_Noyr (0x04) No YEAR (suppresses YEAR in the date string if present)
_Nomon (0x08) No MONTH (suppresses MONTH in the date string if present)
_Noday (0x10) No DAY (suppresses DAY in the date string if present)

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order. For example: _Mdy, _Ymd_Noday, _Cntrydate_Noday_Nomon.

tformat specifies the output time format. The following input options apply to tformat (options which are not listed are ignored):

_Flexhr (0x00) Read time in either 12-hour or 24-hour format, as encountered
_12hr (0x01) Read time in 12-hour format with trailing am/pm strings
_24hr (0x02) Read time in 24-hour format
_Cntryhr (0x03) Read time in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) No HOUR (suppresses HOUR in the time string if present)
_Nomin (0x08) No MINUTES (suppresses MINUTES in the time string if present)
_Nosec (0x10) No SECONDS (suppresses SECONDS in time string if present)
_No100ths (0x20) No 100THS (suppresses 100THS in the time string if present)

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths, _Nosec_No100ths.

precision specifies the number of digits to be read to the right of the decimal point. However, if more digits are encountered they are skipped (up to the limit imposed by width). precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following input options may be combined with precision (options which are not listed are ignored):

_Fill (0x40) Pad characters after the fractional portion are skipped (up to precision total characters)
_Round (0x00) Round the final significant digit of the input value if more digits are present
_Trunc (0x20) Truncate the final significant digit of the input value if more digits are present.

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Fill, _10_Fill_Trunc.

width specifies the maximum width of the input field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be processed for a specific value. If field overflow characters are encountered when reading a value, an error is returned (if field overflow checking is enabled) or the read is simply skipped (if field overflow checking is not enabled). A width of zero (_Nolimit) is the same as the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.
WARNING! This function uses approximately 250 bytes of stack space.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

The following input script reads two float values from a handle (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	{
	   float xloc, yloc;
	   int count;
	   _put_str("\n\rInput X,Y coordinates: ");
	   _hget_script(0, &count, __FLOAT_P _Nolimit _2 _Calign 
	   	  _SKPCHR ","
	           __FLOAT_P _Nolimit _2 _Calign, &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include <script.h>
	{
	   char *str;
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	        _SKPCHR ","
	   	        __FLOAT_P _Nolimit _2 _Calign_Exp;
	   float xloc, yloc;
	   float *xy_params[2];
	   
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load param list w/ptrs */
	xy_read:
	   str = "\n\rInput X,Y coordinates: ";   
	   mov si,str	/* SI = offset of str */
	   cput_str();	/* display prompt */
	   lea si,xy_script /* SI = offset of xy_script */
	   lea di,xy_params/* DI = offset param list */
	   xor bx,bx	/* BX = handle of STDIN */
	   hget_script();     /* read x,y coordinates, 
	   	  	 	     CX = num char written */
	    je ok
	    ja again
	   jmp xy_read	    /* error, invalid input */

	again:	  	 	/* error, insufficient input */
	      jmpxy_read	
	ok:	  	 	/* successful, continue */
	   ...
	}

Source file _SIOHGET.ASM ASM equiv HGET_SCRIPT
See also
_cget_s, _get_script, _hget_str, _hput_script, _sget_script, sio_addr, _vget_script

_hput_script


Descrip
Uses an output script to write data to a file or device.

Syntax
#include <script.h>
int _hput_script(int handle, int *count, const char *outscript[,paramlist,...]);

Returns
0 if the output script was successfully processed.
count total number of characters written
s_status final script status (error code is SE_OK)

1 if an error occurred after output data was partially written to handle.
count number of characters actually written
s_status final script status (error code indicates error type, which may be SE_EOF)

-1 if an error occurred before any writes were performed.
count zero
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to the file or device associated with handle. 0 is returned if the script was successfully processed. 1 is returned if an error occurred after some output data was written to handle. -1 is returned if an error occurred before any data could be written to handle. count always indicates the number of characters actually written. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

If s_status.ecode equals SE_DOS on return, then a DOS error occurred and the DOS error code is contained in e_code. A value of SE_EOF is returned in s_status.ecode if the disk is full or if a Ctrl-Z is written to a "cookedmode" character device (such as STDOUT) with additional output characters following the Ctrl-Z character. The SE_EOF condition is possible only if the return value is 1.

If handle is associated with a file, output data is written to the file starting at the current file pointer position. The file pointer is advanced past the last character written. 0 is returned immediately if processing of outscript does not require any characters to be written. No write is performed since this would cause DOS to truncate the file at the current input pointer position.

External parameters to outscript are specified as individual arguments following outscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes. (The _BEL, _BS, _TAB, _LF, and _CR codes may only be used if STDOUT is specified as the output device).

Script Code Summary

The following tables summarize the output script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffix Type of parameter expected on parameter list

None Immediate value (pointer if a string is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times
_CHRI,char _ Process char without
interpretation

_STRI,string _ Process string
without
interpretation
_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist * and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any Skip the next
parameter in the
parameter list

Console I/O Codes

Script code, arg(s) Parameter list Description

_BEL _ Beep

_BS _ Backspace

_LF _ Line feed

_CR _ Carriage return

_TAB _ Tab


Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record (writes a
record delimiter)

_TOFIELD _ Advance to next
field (writes a
field delimiter)

_TOSPACE _ Skip to next space
or TAB (writes a
space character)

_TOCHR,char _ Advance past next
occurrence of char
(writes char)

_TOSTR,string _ Advance past next
occurrence of string
(writes string)

_TOSET,charset _ Advance past next
occurrence of any
character in charset
(writes the first
character in
charset)

_SKPCNT,count _ Skip the next count
characters (writes
count space
characters)

_SKPSPACE _ Skip an optional
space or TAB
character (writes a
space character)

_SKPCHR,char _ Skip an optional
char (writes char)

_SKPSTR,string _ Skip an optional
occurrence of string
(writes string)

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset (writes the
first character in
charset)

_SKPSPACES _ Skip all consecutive
space or TAB
characters (writes a
space character)

_SKPCHRS,char _ Skip all consecutive
occurrences of char
(writes char)

_SKPSTRS,string _ Skip all consecutive
occurrences of
string (writes
string)

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset
(writes the first
character in
charset)

_REQSPACE _ Skip a required
space or TAB (writes
a space character)

_REQCHR,char _ Skip a required
occurrence of char
(writes char)

_REQSTR,string _ Skip a required
occurrence of string
(writes string)

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset (writes the
first character in
charset)

Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width, char Output a formatted
radix,align char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
radix,align quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date


__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string


Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with an NULL character. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively.

The following options apply to nformat, sformat, and align:

_Noalign (0x00) Result is not aligned
_Lalign (0x80) Result is left-aligned
_Ralign (0x40) Result is right-aligned
_Calign (0xC0) Result is center-aligned
_Zalign (0x20) The result is right-aligned using leading zeros

The following options apply to nformat ONLY:

_Noplus (0x00) Suppress plus sign if positive
_Plus (0x10) Force plus sign if positive
_Nocurrency (0x00) Do not output in currency format
_Currency (0x08) Output in currency format
_Nothous (0x00) Do not output thousands separators
_Thous (0x04) Output using thousands separators
_Noexp (0x00) Output in non-exponential format
_Exp (0x01) Output in exponential format
_Flex (0x02) Output in "flex" format (non-exponential if possible)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on output
_Lower (0x02) Convert ASCII characters to lowercase on output

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following options apply to dformat:

_Dmy (0x01) Force DAY/MONTH/YEAR order
_Ymd (0x02) Force YEAR/MONTH/DAY order
_Mdy (0x03) Force MONTH/DAY/YEAR order
_Noyr (0x04) Suppress YEAR in the date string
_Nomon (0x08) Suppress MONTH in the date string
_Noday (0x10) Suppress DAY in the date string
_Padmon (0x00) Pad the MONTH field with a leading zero, if required
_Nopadmon (0x20) Do not zero pad the MONTH field
_Padday (0x00) Pad the DAY field with a leading zero, if required
_Nopadday (0x40) Do not zero pad the DAY field
_2digyr (0x00) Output the YEAR as a 2-digit number
_4digyr (0x80) Output the YEAR as a 4-digit number

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order, followed by pad options in alphabetical order, followed by the year format option. Default options (value equal to 0x00) may be omitted; _Padmon and _Padday are defaults and are always omitted. For example: _Mdy, _Ymd_Noday_Nopadmon_4digyr, _Ymd_Nopadday_Nopadmon_4digyr, _Dmy_4digyr.

tformat specifies the output time format. The following options apply to tformat:

_Flexhr (0x00) Output in country-specified time format (12-hour or 24-hour)
_12hr (0x01) Force 12-hour time format with trailing am/pm strings
_24hr (0x02) Force 24-hour time format
_Cntryhr (0x03) Output in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) Suppress the HOUR field in the time string
_Nomin (0x08) Suppress the MINUTES field in the time string
_Nosec (0x10) Suppress the SECONDS field in the time string
_No100ths (0x20) Suppress the 100THS of seconds field in the time string
_Padtime (0x00) Pad the left-most time field with a leading zero, if required
_Nopadtime (0x40) Do not zero pad the left-most time field

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance, followed by pad options in alphabetical order. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths_Nopadtime.

precision specifies the number of digits to the right of the decimal point. precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following options may be combined with precision:

_Fix (0x00) Pad right with zeros to force precision digits to the right of the decimal point
_Float (0x80) Do not pad digits to the right of the decimal point, if necessary
_Fill (0x40) Pad right with pad characters to force precision digits to the right of the decimal point
_Round (0x00) Round the final significant digit of the result, if required
_Trunc (0x20) Truncate the final significant digit of the result, if required

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Float, _10_Fix_Trunc.

width specifies the maximum width of the output field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be output for any value. If the formatted value would exceed width, an error is returned (if field overflow checking is enabled) or the field is filled with overflow characters(if field overflow checking is disabled). Specifying a width of zero (_Nolimit) is the same as specifying the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

C/C++ Example
	{
	   int count;
	   float xloc = 12.70, yloc = -34.0;
	   _hput_script(1, &count, "\n\rX co-ordinate: " 
	   	  __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   	  "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	  _Ralign, &xloc, &yloc);
	   /* output x,y coordinates to STDOUT */
	   ...
	}

Inline Assembly Example
	#include <script.h>
	{
	   char xy_script[] = "\n\rX co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	        _Ralign _REP _12
	   	        "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	        _Ralign;
	   float xloc = 12.70, yloc = -34.0;
	   float *xy_params[2];
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load param list w/ptrs */
	   mov bx,1	/* BX = standard out */
	   pushss
	   pop es	 	/* ES = SS (params on stack) */
	   lea si,xy_script/* SI = offset script string */
	   lea di,xy_params/* DI = offset of param list */
	   hput_script();	/* output x,y coordinates, 
	   	  	 	     CX = num char written */
	   ...
	}

Source file _SIOHPUT.ASM ASM equiv HPUT_SCRIPT
See also
_cput_script, _hget_script, _hput_script, _hput_str, _put_script, sio_addr, _sput_script

_put_script


Descrip
Uses an output script to write data to STDOUT.

Syntax
#include <script.h>
int _put_script(const char *outscript[,paramlist,...]);

Returns
0 if the output script was successfully processed.
s_status final script status (error code is SE_OK)

-1 if an error occurred.
s_status final script status (error code indicates exact error)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to STDOUT. 0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

If s_status.ecode equals SE_DOS on return, then a DOS error occurred and the DOS error code is contained in e_code. s_status.ecode is set to SE_EOF if the disk is full or if a Ctrl-Z is written to a "cooked mode" character device (such as STDOUT) with additional output characters following the Ctrl-Z character.

External parameters to outscript are specified as individual arguments following outscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes (except for _BEL, _BS, _TAB, _LF, and _CR, which are correctly interpreted by STDOUT).

Script Code Summary

The following tables summarize the output script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffixType of parameter expected on parameter list

None Immediate value (pointer if a string is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times

_CHRI,char _ Process char without
interpretation

_STRI,string _ Process string
without interpretation

_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist * and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any Skip the next
parameter in the
parameter list

Console I/O Codes

Script code, arg(s) Parameter list Description

_BEL _ Beep

_BS _ Backspace
_LF _ Line feed

_CR _ Carriage return

_TAB _ Tab

Data Synchronization Codes






Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record (writes a
record delimiter)

_TOFIELD _ Advance to next
field (writes a
field delimiter)

_TOSPACE _ Skip to next space
or TAB (writes a
space character)

_TOCHR,char _ Advance past next
occurrence of char
(writes char)

_TOSTR,string _ Advance past next
occurrence of string
(writes string)

_TOSET,charset _ Advance past next
occurrence of any
character in charset
(writes the first
character in
charset)

_SKPCNT,count _ Skip the next count
characters (writes
count space
characters)

_SKPSPACE _ Skip an optional
space or TAB
character (writes a
space character)

_SKPCHR,char _ Skip an optional
char (writes char)

_SKPSTR,string _ Skip an optional
occurrence of string
(writes string)

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset (writes the
first character in
charset)

_SKPSPACES _ Skip all consecutive
space or TAB
characters (writes a
space character)

_SKPCHRS,char _ Skip all consecutive
occurrences of char
(writes char)

_SKPSTRS,string _ Skip all consecutive
occurrences of
string (writes
string)

_SKPSETS,charset _ Skip all consecutive
character in charset
occurrences of any
(writes the first
character in
charset)

_REQSPACE _ Skip a required
a space character)
space or TAB (writes

_REQCHR,char _ Skip a required
occurrence of char
(writes char)

_REQSTR,string _ occurrence of string
Skip a required
(writes string)

_REQSET,charset _ Skip a single,
required occurrence
charset (writes the
of any character in
first character in
charset)


Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width, char Output a formatted
radix,align char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix


__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
radix,align quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double


__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string


Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with an NULL character. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively.

The following options apply to nformat, sformat and align:

_Noalign (0x00) Result is not aligned
_Lalign (0x80) Result is left-aligned
_Ralign (0x40) Result is right-aligned
_Calign (0xC0) Result is center-aligned
_Zalign (0x20) The result is right-aligned using leading zeros

The following options apply to nformat ONLY:

_Noplus (0x00) Suppress plus sign if positive
_Plus (0x10) Force plus sign if positive
_Nocurrency (0x00) Do not output in currency format
_Currency (0x08) Output in currency format
_Nothous (0x00) Do not output thousands separators
_Thous (0x04) Output using thousands separators
_Noexp (0x00) Output in non-exponential format
_Exp (0x01) Output in exponential format
_Flex (0x02) Output in "flex" format (non-exponential if possible)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on output
_Lower (0x02) Convert ASCII characters to lowercase on output

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following options apply to dformat:

_Cntrydate (0x00) Use country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Force DAY/MONTH/YEAR order
_Ymd (0x02) Force YEAR/MONTH/DAY order
_Mdy (0x03) Force MONTH/DAY/YEAR order
_Noyr (0x04) Suppress YEAR in the date string
_Nomon (0x08) Suppress MONTH in the date string
_Noday (0x10) Suppress DAY in the date string
_Padmon (0x00) Pad the MONTH field with a leading zero, if required
_Nopadmon (0x20) Do not zero pad the MONTH field
_Padday (0x00) Pad the DAY field with a leading zero, if required
_Nopadday (0x40) Do not zero pad the DAY field
_2digyr (0x00) Output the YEAR as a 2-digit number
_4digyr (0x80) Output the YEAR as a 4-digit number

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order, followed by pad options in alphabetical order, followed by the year format option. Default options (value equal to 0x00) may be omitted; _Padmon and _Padday are defaults and are always omitted. For example: _Mdy, _Ymd_Noday_Nopadmon_4digyr, _Ymd_Nopadday_Nopadmon_4digyr, _Dmy_4digyr.

tformat specifies the output time format. The following options apply to tformat:

_Flexhr (0x00) Output in country-specified time format (12-hour or 24-hour)
_12hr (0x01) Force 12-hour time format with trailing am/pm strings
_24hr (0x02) Force 24-hour time format
_Cntryhr (0x03) Output in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) Suppress the HOUR field in the time string
_Nomin (0x08) Suppress the MINUTES field in the time string
_Nosec (0x10) Suppress the SECONDS field in the time string
_No100ths (0x20) Suppress the 100THS of seconds field in the time string
_Padtime (0x00) Pad the left-most time field with a leading zero, if required
_Nopadtime (0x40) Do not zero pad the left-most time field

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance, followed by pad options in alphabetical order. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths_Nopadtime.

precision specifies the number of digits to the right of the decimal point. precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following options may be combined with precision:

_Fix (0x00) Pad right with zeros to force precision digits to the right of the decimal point
_Float (0x80) Do not pad digits to the right of the decimal point, if necessary
_Fill (0x40) Pad right with pad characters to force precision digits to the right of the decimal point
_Round (0x00) Round the final significant digit of the result, if required
_Trunc (0x20) Truncate the final significant digit of the result, if required

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Float, _10_Fix_Trunc.

width specifies the maximum width of the output field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be output for any value. If the formatted value would exceed width, an error is returned (if field overflow checking is enabled) or the field is filled with overflow characters (if field overflow checking is disabled). Specifying a width of zero (_Nolimit) is the same as specifying the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC?.LIB) must also be linked in (see the Scripted I/O technical notes).

C/C++ Example
	{
	   float xloc = 12.70, yloc = -34.0;
	   _put_script("\n\rX co-ordinate: "__FLOAT_P _8 _2_Fix _Ralign
	         _REP _12 " "
	         "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix _Ralign,
	         &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   char xy_script[] = "\n\rX co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	    _Ralign _REP _12 " "
	   	    "\n\rY co-ordinate: "__FLOAT_P _8 _2_Fix 
	   	    _Ralign;
	   float xloc = 12.70, yloc = -34.0;
	   float *xy_params[2];
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load parameter list w/ptrs */
	   pushss
	   pop es	 	/* ES=SS (param list on stack) */
	   lea si,xy_script /* SI = offset of script */
	   lea di,xy_params /* DI = offset of param list */
	   put_script();	/* output x,y coordinates */
	   ...
	}

Source file _SIODPUT.ASM ASM equiv PUT_SCRIPT
See also
_cput_script, _get_script, _hput_script, _put_str, _sput_script, sio_addr, _vput_script

_sget_script


Descrip
Reads and interprets an ASCIIZ string using an input script.

Syntax
#include <script.h>
int _sget_script(int *count, char *string, const char *inscript[,paramlist,...]);

Returns
0 if the input was successfully read using the input script.
count number of characters read from string
s_status final script status (error code is SE_OK)

1 if end-of-string was encountered before the input script could be fully processed.
count number of characters read from string
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
count number of characters read from string
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an ASCIIZ input string (string) as specified in the input script (inscript). As values are read from string they are stored as specified by the parameter list (paramlist). 0 is returned if the script was successfully processed. 1 is returned if end-of-string was encountered before inscript could be fully processed. -1 is returned if an error occurred. For all return conditions count is returned with the number of characters actually read. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

The ASCIIZ data in string is always processed sequentially, a character at a time, beginning with the first byte in string, as specified in inscript. Under no condition is any data processed past the end of string.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-string is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-string was encountered.

External parameters to inscript are specified as individual arguments following inscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

Script Code Summary

The following tables summarize the input script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffixType of parameter expected on parameter list

None Immediate value (pointer if a string or structure is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
count times

_CHRI,char _ Match char without
interpreting it

_STRI,string _ Match string
interpreting it
without

_SCRIPT,script _ Process script as
an embedded script

__CALL... script *, Call a new script
paramlist * list
and/or parameter

__CHAIN... script *, Chain to a new
paramlist * script and/or
parameter list

__SKPPARAM,size any parameter in the
Skip the next
parameter list

Data Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record

_TOFIELD _ Advance to next
field

_TOSPACE _ Skip to next space
or TAB

_TOCHR,char _ Advance past next
occurrence of char

_TOSTR,string _ Advance past next
occurrence of string

_TOSET,charset _ Advance past next
occurrence of any
character in charset

_SKPCNT,count _ Skip the next count
characters

_SKPSPACE _ Skip an optional
space or TAB
character

_SKPCHR,char _ Skip an optional
char

_SKPSTR,string _ Skip an optional
occurrence of string

_SKPSET,charset _ Skip a single,
optional occurrence
of any character in
charset

_SKPSPACES _ Skip all consecutive
space or TAB
characters

_SKPCHRS,char _ Skip all consecutive
occurrences of char

_SKPSTRS,string _ Skip all consecutive
occurrences of
string

_SKPSETS,charset _ Skip all consecutive
occurrences of any
character in charset

_REQSPACE _ Skip a required
space or TAB

_REQCHR,char _ Skip a required
occurrence of char

_REQSTR,string _ Skip a required
occurrence of string

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset

Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width,
radix,align char Output a formatted
char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
radix,align quad in a specified
radix


__FXPINT...,width, int Output a formatted precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string

Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with a NULL. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively. These options are flexibly interpreted in input scripts to facilitate reading of formatted values without unnecessarily constraining the input format. For example, if an unaligned value is written, it may be read using any input alignment type.

The following options apply to nformat, sformat, and align:

_Noalign (0x00) No leading or trailing pad characters are skipped
_Lalign (0x80) Trailing pad characters are skipped
_Ralign (0x40) Leading pad characters are skipped
_Calign (0xC0) Leading and trailing pad characters are skipped

The following options apply to nformat ONLY:

_Noplus (0x00) Do not allow plus sign
_Plus (0x10) Allow plus sign for positive values
_Nocurrency (0x00) Do not allow currency format
_Currency (0x08) Allow currency format
_Nothous (0x00) Do not allow thousands separators
_Thous (0x04) Allow thousands separators
_Noexp (0x00) Do not allow exponential format (ignores exponent if present)
_Exp (0x01) Allow exponential format (reads exponent if present)
_Flex (0x02) Allow exponential format (reads exponent if present)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on input
_Lower (0x02) Convert ASCII characters to lowercase on input

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (options equal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following input options apply to dformat (options which are not listed are ignored):

_Cntrydate (0x00) Read date using country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Read date using DAY/MONTH/YEAR order
_Ymd (0x02) Read date using YEAR/MONTH/DAY order
_Mdy (0x03) Read date using MONTH/DAY/YEAR order
_Noyr (0x04) No YEAR (suppresses YEAR in the date string if present)
_Nomon (0x08) No MONTH (suppresses MONTH in the date string if present)
_Noday (0x10) No DAY (suppresses DAY in the date string if present)

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order. For example: _Mdy, _Ymd_Noday, _Cntrydate_Noday_Nomon.

tformat specifies the output time format. The following input options apply to tformat (options which are not listed are ignored):

_Flexhr (0x00) Read time in either 12-hour or 24-hour format, as encountered
_12hr (0x01) Read time in 12-hour format with trailing am/pm strings
_24hr (0x02) Read time in 24-hour format
_Cntryhr (0x03) Read time in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) No HOUR (suppresses HOUR in the time string if present)
_Nomin (0x08) No MINUTES (suppresses MINUTES in the time string if present)
_Nosec (0x10) No SECONDS (suppresses SECONDS in time string if present)
_No100ths (0x20) No 100THS (suppresses 100THS in the time string if present)

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths, _Nosec_No100ths.

precision specifies the number of digits to be read to the right of the decimal point. However, if more digits are encountered they are skipped (up to the limit imposed by width). precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following input options may be combined with precision (options which are not listed are ignored):

_Fill (0x40) Pad characters after the fractional portion are skipped (up to precision total characters)
_Round (0x00) Round the final significant digit of the input value if more digits are present
_Trunc (0x20) Truncate the final significant digit of the input value if more digits are present

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Fill, _10_Fill_Trunc.

width specifies the maximum width of the input field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be processed for a specific value. If field overflow characters are encountered when reading a value, an error is returned (if field overflow checking is enabled) or the read is simply skipped (if field overflow checking is not enabled). A width of zero (_Nolimit) is the same as the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC??.LIB) must also be linked in (see the Scripted I/O technical notes).

The following input script reads two float values from the keyboard (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	{
	int count;
	float xloc, yloc;
	   _sget_script(&count,"  1.234 , 1.32342 ",
	   	  __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	  _SKPCHR ","
	           __FLOAT_P _Nolimit _2 _Calign_Exp, 
	   	  &xloc, &yloc);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	char *str;
	char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	     _SKPCHR ","
	   	     __FLOAT_P _Nolimit _2 _Calign_Exp;
	float xloc, yloc;
	float *xy_params[2];
	   ...
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;/* load parameter list w/ptrs */
	   str = "1.234,1.655";/* string to convert */
	   mov ax,str
	   mov bx,ss	/* BX:AX -> string */
	   pushss
	   pop es	 	/* ES=DS (param list on stack) */
	   lea si,xy_script /* SI = offset script string */
	   lea di,xy_params /* DI = offset param list */
	   sget_script();   /* read x,y coordinates, 
	   	  	 	   CX = num char written */
	   ...
	}

Source file _SIOSGET.ASM ASM equiv SGET_SCRIPT
See also
_cget_s, _get_script, _hget_script, _sput_script, sio_addr, _vsget_script

sio_addr


Descrip
(Variable) Contains the address of the current scripted I/O options structure.

Syntax
#include <script.h>
extern sioopts *sio_addr;

Notes
This pointer variable maintains the address of the current scripted I/O options structure. In small data models (TINY, SMALL, MEDIUM), this variable is a near pointer which contains the offset of the structure within the global data segment (DGROUP). In large data models (COMPACT, LARGE, HUGE), this variable is a far pointer which contains the segment and offset of the structure.

The current sioopts structure specifies global scripted I/O options and is used by all of the scripted I/O functions. The behavior of the scripted I/O functions may be changed by modifying this structure or by modifying sio_addr to point to a different sioopts structure.

sio_addr is initialized with the address of the default sioopts structure. The sioopts structure is defined in SCRIPT.H as follows:

typedef struct {
char *sio_fdelim; /* address of ASCIIZ field delimiter string (NULL) */
char *sio_rdelim; /* address of ASCIIZ record delimiter string (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 (0=disable all) (0) */
} sioopts;

The default value for each field in the default sioopts structure is shown in parentheses in the comments above.

The following symbolic constants (defined in SCRIPT.H) may be used to check or modify information in the sio_eflags field:

SIO_NOCHKFOV (0x00) Field overflow does NOT cause an error return
SIO_CHKFOV (0x01) Field overflow causes an error return
SIO_NOCHKFUND (0x00) Field underflow does NOT cause an error return
SIO_CHKFUND (0x02) Field underflow causes an error return
SIO_NOCHKNOV (0x00) Numeric overflow does NOT cause an error return
SIO_CHKNOV (0x04) Numeric overflow causes an error return
SIO_NOCHKNUND (0x00) Numeric underflow does NOT cause an error return
SIO_CHKNUND (0x08) Numeric underflow causes an error return
SIO_NOCHKDATE (0x00) Invalid date/time does NOT cause an error return
SIO_CHKDATE (0x10) Invalid date/time causes an error return
SIO_NOCHKCHAR (0x00) Unmatched required char does NOT cause an error return
SIO_CHKCHAR (0x20) Unmatched required char causes an error return

Source file SIOVARS.ASM ASM equivâ
See also
_cput_script, _cget_s, _get_script, _hget_script, _hput_script, _put_script, _sget_script, _sput_script, _vcget_script, _vcput_script, _vget_script, _vhget_script, _vhput_script, _vput_script, _vsget_script, _vsput_script

_sput_script


Descrip
Uses an output script to write data to an ASCIIZ string.

Syntax
#include <script.h>
int _sput_script(int size, int *count, char *buffer, char *outscript[,paramlist,...]);

Returns
0 if the script was successfully processed.
buffer resulting ASCIIZ string
count length of the ASCIIZ string written to buffer
s_status final script status (error code is SE_OK)

-1 if an error occurred.
buffer partial ASCIIZ string
count length of the partial ASCIIZ string written to buffer
s_status final script status (error code indicates error type, which may be SE_EOF)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to buffer in ASCIIZ format. 0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.e_code indicating the error type, if any. In all cases, count returns the length of the output ASCIIZ string excluding the terminal NULL.

If s_status.ecode equals SE_EOF on return, then the end of buffer was encountered before outscript could be fully processed.

The length of the resulting ASCIIZ string (excluding the terminal NULL) is never greater than size-1 bytes.

External parameters to outscript are specified as individual arguments following outscript. These arguments are collectively referred to as the parameter list (paramlist). By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-
far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-
0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes.

Script Code Summary

The following tables summarize the output script codes defined in SCRIPT.H.

Three terminal period characters ("...") are used below to denote codes with four variations to denote the type of parameter which is expected on the parameter list, as follows:

CODE... suffixType of parameter expected on parameter list

None Immediate value (pointer if a string is expected)
..._P Pointer (near in small data models, far in large data models)
..._N near pointer
..._F far pointer

More detailed descriptions of the following codes are provided in the Scripted I/O technical notes.

Flow Control Codes

Script code, arg(s) Parameter list Description

_END _ End of script,
string, or charset

_REP,count _ Repeat the next
character or code
_CHRI,char _ count times
Process char without
interpretation

_STRI,string _ Process string
without
interpretation

_SCRIPT,script _ Process script as an
embedded script

__CALL... script *, Call a new script
paramlist * and/or parameter
list

__CHAIN... script *, Chain to a new
paramlist * script and/or

__SKPPARAM,size any Skip the next
parameter list
parameter in the
parameter list

Synchronization Codes

Script code, arg(s) Parameter list Description

_TORECORD _ Advance to next
record (writes a
record delimiter)

_TOFIELD _ Advance to next
field (writes a
field delimiter)

_TOSPACE _ Skip to next space
or TAB (writes a
space character)

_TOCHR,char _ Advance past next
occurrence of char
(writes char)

_TOSTR,string _ Advance past next
(writes string)
occurrence of string

_TOSET,charset _ Advance past next
occurrence of any
character in charset
(writes the first
character in

_SKPCNT,count _ Skip the next count
characters (writes
charset)
count space
characters)

_SKPSPACE _ Skip an optional
space or TAB
character (writes a
space character)

_SKPCHR,char _ Skip an optional
char (writes char)

_SKPSTR,string _ Skip an optional
occurrence of string

_SKPSET,charset _ (writes string)
Skip a single,
optional occurrence
of any character in
charset (writes the
first character in
charset)

_SKPSPACES _ Skip all consecutive
space or TAB
characters (writes a
space character)

_SKPCHRS,char _ Skip all consecutive
occurrences of char
(writes char)

_SKPSTRS,string _ Skip all consecutive
occurrences of
string (writes
string)

_SKPSETS,charset _ Skip all consecutive
character in charset
occurrences of any
(writes the first
character in
charset)

_REQSPACE _ Skip a required
space or TAB (writes
a space character)
_REQCHR,char _
Skip a required
occurrence of char
(writes char)

_REQSTR,string _ Skip a required
occurrence of string
(writes string)

_REQSET,charset _ Skip a single,
required occurrence
of any character in
charset (writes the
first character in
charset)
Formatted Data Conversion Codes

Script code, arg(s) Parameter list Description

_UNSIGNED _ Next integer or
fixed-point value is
unsigned

__CHAR...,width,nformat char Output a formatted
char

__INT...,width,nformat int Output a formatted
int

__LONG...,width,nformat long Output a formatted
long

__QUAD...,width,nformat quad Output a formatted
quad

__ASCCHAR...,width, char Output a formatted
radix,align char in a specified
radix

__ASCINT...,width,radix,align int Output a formatted
int in a specified
radix

__ASCLONG...,width, long Output a formatted
radix,align long in a specified
radix

__ASCQUAD...,width, quad Output a formatted
radix,align quad in a specified
radix

__FXPINT...,width, int Output a formatted
precision,nformat fixed-point int

__FXPLONG...,width, long Output a formatted
precision,nformat fixed-point long

__FXPQUAD...,width, quad Output a formatted
precision,nformat fixed-point quad

__FLOAT...,width, float Output a formatted
precision,nformat float

__DOUBLE...,width, double Output a formatted
precision,nformat double

__LDOUBLE...,width, long double Output a formatted
precision,nformat long double

__BCD...,width,nformat bcd Output a formatted
packed bcd

__NEARPTR...,width,sformat near * Output a formatted
near pointer

__FARPTR...,width,sformat far * Output a formatted
far pointer

__DATE...,width, long date Output a formatted
dformat,sformat long date

__TIME...,width, long time Output a formatted
tformat,sformat long time

__CHARACTER...,width,sformat char Output a formatted
ASCII character

__STRING...,width,sformat char * Output a formatted
ASCII string


Arguments

As used above, string and charset denote ASCIIZ string arguments (delimited with a NULL). script denotes any sequence of characters and/or script codes delimited with an NULL character. count and size denote arguments with values in the range 0x00-0xFE. char denotes any character code in the range 0x00-0xFE.

Values of 0xFF may be specified for arguments or as initial characters in a string or charset ONLY by using the _0xFF or _255 equates or by inserting two 0xFF codes in succession:

_255 (0xFF,0xFF) Specifies an argument value of 255 (-1)
_0xFF (0xFF,0xFF) Specifies an argument value of 255 (-1)

The following codes may be used in place of any argument (shown in italics) to specify that the argument is to be obtained from the parameter list:

Script code, Parameter Description
arg(s) list



__Arg char arg Obtain argument from
(ptr if parameter list
__Arg_p applicable)
__Arg_n char * arg
__Arg_f char near *
arg
char far *
arg



Formatted Data Conversion Arguments

The nformat, sformat, and align arguments are used to specify numeric, string, and alignment-only formatting options, respectively.

The following options apply to nformat, sformat and align:

_Noalign (0x00) Result is not aligned
_Lalign (0x80) Result is left-aligned
_Ralign (0x40) Result is right-aligned
_Calign (0xC0) Result is center-aligned
_Zalign (0x20) The result is right-aligned using leading zeros

The following options apply to nformat ONLY:

_Noplus (0x00) Suppress plus sign if positive
_Plus (0x10) Force plus sign if positive
_Nocurrency (0x00) Do not output in currency format
_Currency (0x08) Output in currency format
_Nothous (0x00) Do not output thousands separators
_Thous (0x04) Output using thousands separators
_Noexp (0x00) Output in non-exponential format
_Exp (0x01) Output in exponential format
_Flex (0x02) Output in "flex" format (non-exponential if possible)

The following options apply to sformat ONLY:

_Nocase (0x00) Do not convert to uppercase or lowercase
_Upper (0x01) Convert ASCII characters to uppercase on output
_Lower (0x02) Convert ASCII characters to lowercase on output

Symbolic constants for all valid combinations of nformat options are defined in SCRIPT.H. The exponential format option is always specified first, followed by the alignment option, followed by all other non-default options (options not equal to 0x00) in alphabetical order. Default options (optionsequal to 0x00) may be omitted. For example: _Noexp_Ralign, _Flex_Calign_Plus, _Ralign_Currency_Plus_Thous, _Lalign_Currency.

dformat specifies the output date format. The following options apply to dformat:

_Cntrydate (0x00) Use country-specified DAY/MONTH/YEAR order
_Dmy (0x01) Force DAY/MONTH/YEAR order
_Ymd (0x02) Force YEAR/MONTH/DAY order
_Mdy (0x03) Force MONTH/DAY/YEAR order
_Noyr (0x04) Suppress YEAR in the date string
_Nomon (0x08) Suppress MONTH in the date string
_Noday (0x10) Suppress DAY in the date string
_Padmon (0x00) Pad the MONTH field with a leading zero, if required
_Nopadmon (0x20) Do not zero pad the MONTH field
_Padday (0x00) Pad the DAY field with a leading zero, if required
_Nopadday (0x40) Do not zero pad the DAY field
_2digyr (0x00) Output the YEAR as a 2-digit number
_4digyr (0x80) Output the YEAR as a 4-digit number

Symbolic constants for all valid combinations of dformat options are defined in SCRIPT.H. The _Dmy, _Ymd, _Mdy, or _Cntrydate option is always specified first, followed by suppress options in alphabetical order, followed by pad options in alphabetical order, followed by the year format option. Default options (value equal to 0x00) may be omitted; _Padmon and _Padday are defaults and are always omitted. For example: _Mdy, _Ymd_Noday_Nopadmon_4digyr, _Ymd_Nopadday_Nopadmon_4digyr, _Dmy_4digyr.

tformat specifies the output time format. The following options apply to tformat:

_Flexhr (0x00) Output in country-specified time format (12-hour or 24-hour)
_12hr (0x01) Force 12-hour time format with trailing am/pm strings
_24hr (0x02) Force 24-hour time format
_Cntryhr (0x03) Output in country-specified time format (12-hour or 24-hour)
_Nohr (0x04) Suppress the HOUR field in the time string
_Nomin (0x08) Suppress the MINUTES field in the time string
_Nosec (0x10) Suppress the SECONDS field in the time string
_No100ths (0x20) Suppress the 100THS of seconds field in the time string
_Padtime (0x00) Pad the left-most time field with a leading zero, if required
_Nopadtime (0x40) Do not zero pad the left-most time field

Symbolic constants for all valid combinations of tformat options are defined in SCRIPT.H. The hour format (_12hr, _24hr, _Flexhr, or _Cntryhr) option is always specified first, followed by suppress options in order of significance, followed by pad options in alphabetical order. Default options (value equal to 0x00) may be omitted. For example: _12hr, _24hr_Nosec_No100ths, _Cntryhr_No100ths_Nopadtime.

precision specifies the number of digits to the right of the decimal point. precision must be a value in the range 0..30. A value of 31 (_Cdigits) may also be specified:

_Cdigits (0x1F) Use the country-specified number of currency digits as precision

In addition, the following options may be combined with precision:

_Fix (0x00) Pad right with zeros to force precision digits to the right of the decimal point
_Float (0x80) Do not pad digits to the right of the decimal point, if necessary
_Fill (0x40) Pad right with pad characters to force precision digits to the right of the decimal point
_Round (0x00) Round the final significant digit of the result, if required
_Trunc (0x20) Truncate the final significant digit of the result, if required

Symbolic constants for all valid combinations of precision options are defined in SCRIPT.H. The numeric value of precision (or _Cdigits) is always specified first with a leading underscore, followed by any other options in alphabetical order. Default options (options with a value of 0x00) may be omitted. For example: _15, _Cdigits, _0_Round, _2_Float, _10_Fix_Trunc.

width specifies the maximum width of the output field, in characters. width must be a value in the range 0..126. Under no conditions will more than width characters be output for any value. If the formatted value would exceed width, an error is returned (if field overflow checking is enabled) or the field is filled with overflow characters (if field overflow checking is disabled). Specifying a width of zero (_Nolimit) is the same as specifying the maximum supported width (at least 126 characters):

_Nolimit (0x00) Designates the maximum supported width (at least 126 characters)

radix specifies the radix of the result (a radix of 2 denotes binary, 8 denotes octal, 16 denotes hexadecimal). radix must be a value in the range 2..36.

See Appendix H for a complete scripted I/O function-to-code cross reference.

WARNING! This function requires an 8087 compatible math coprocessor or emulator. When this function is used, the appropriate floating-point conversion library (_FPC??.LIB) must also be linked in (see the Scripted I/O technical notes).

C/C++ Example
	{
	   char buffer[126];
	   int count;
	   float xloc = 12.70, yloc = -34.0;
	   _sput_script(sizeof(buffer),&count,buffer,"\n\rX co-ordinate: "
	            __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   	  "\n\rY co-ordinate: "
	   	  __FLOAT_P _8 _2_Fix _Ralign, &xloc, &yloc);
	   	  /* output result to buffer */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	{
	   float xloc = 12.70, yloc = -34.0;
	   float *xy_params[2];
	   char buffer[126];
	   char xy_script[] = "\n\rX co-ordinate: "
	   	        __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   	        "\n\rY co-ordinate: "
	   	        __FLOAT_P _8 _2_Fix _Ralign;
	   ... 
	   xy_params[0] = &xloc;
	   xy_params[1] = &yloc;
	   mov cx,126	/* CX = size of buffer */
	   mov bx,ss
	   lea ax,buffer /* BX:AX -> output buffer */
	   pushss
	   pop es	 	/* ES=SS (params on stack) */
	   lea si,xy_script /* SI -> script string */
	   lea di,xy_params /* DI -> parameter list */
	   sput_script();	/* output result to buffer */
	   ...
	}

Source file _SIOSPUT.ASM ASM equiv SPUT_SCRIPT
See also
_cput_script, _hput_script, _put_script, _sget_script, sio_addr, _vsput_script

_vcget_script


Descrip
Reads and interprets console I/O keyboard input using an input script and a pointer to a parameter list.

Syntax
#include <script.h>
int _vcget_script(int count, const char *inscript, void *paramlist);

Returns
0 if the input was successfully read using the input script.
s_status final script status (error code is SE_OK)

1 if end-of-input was encountered before the input script could be fully processed.
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads keyboard data into a temporary buffer using the _cget_str function or its equivalent and interprets the input string as specified in the input script (inscript). No more than count characters or a single line of text is read and echoed to the display (whichever is encountered first). The input data is interpreted as specified in inscript and the resulting values are stored as specified by the parameter list (paramlist). This function provides the same functionality as _cget_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. 1 is returned if end-of-input was encountered before inscript could be fully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Keyboard input is always processed sequentially, a character at a time, beginning with the first keyboard input character, as specified in inscript. Under no condition is more than one line of keyboard input read to satisfy the script.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-input is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-input was encountered.

_console_init must be called before using this function.

External parameters to inscript are passed via paramlist, which must be a structure containing the same argument list data which would follow inscript if _cget_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

See _cget_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.
The following input script reads two float values from the keyboard (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	float num;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num, -34.0};
	   ...
	{
	   _cput_str("\n\rInput X,Y coordinates: ");
	   _vcget_script(126,__FLOAT_P _Nolimit _2 _Calign
	   	    _SKPCHR ","
	   	    __FLOAT _Nolimit _2 _Calign, &params);
	   ...
	}

Inline Assembly Example
	#include <include.h>
	float xloc, yloc;
	float *xy_params[2] = {&xloc, &yloc};
	   ...
	{
	char *str = "\n\rInput X,Y coordinates: ";
	char *xy_script = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	        _SKPCHR ","
	   	        __FLOAT_P _Nolimit _2 _Calign_Exp;
	   mov cx,126
	xy_read:
	   lea si,str	/* SI -> message */
	   cput_str();
	   lea si,xy_script/* SI -> script string */
	   mov di,xy_params/* DI -> parameter list */
	   vcget_script();   /* read x,y coordinates */
	    je ok
	    ja again
	   jmp xy_read	    /* error, invalid input */
	again:...	 	/* error, insufficient input */
	   jmp xy_read	

	ok:... 	 	/* successful, continue */
	}

Source file _SIOVCGT.ASM ASM equiv CGET_SCRIPT
See also
_cget_s, _vcput_script, sio_addr, _vsget_script

_vcput_script


Descrip
Uses an output script and a pointer to a parameter list to write data to the display (console I/O system).

Syntax
#include <script.h>
int _vcput_script(const char *outscript, void *paramlist)

Returns
0 if the output script was successfully processed.
s_status final script status (error code is SE_OK)

1 if an error occurred.
s_status final script status (error code indicates exact error)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to the current display using the console I/O system. This function provides the same functionality as _cput_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Output data is written to the display starting at cursor position and continuing in the cursor advance direction. The cursor is advanced past each character written. Output is restricted to the clipping region if the clipping region is enabled; otherwise, it is restricted to the active screen (or the active window if windowing is in effect). Characters are written to the display through BIOS calls or directly to video memory depending on the state of the direct_video variable.

outscript may include console I/O control codes to change console I/O system options as the script is processed, including current display attribute, cursor advance direction, clipping region, etc. Such changes remain in effect after the script has been processed.

_console_init must be called before using this function.

External parameters to outscript are passed via paramlist, which must be a structure containing the same argument list data which would follow outscript if _cput_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x20-0x7E and 0xB0-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x1F, 0x7F-0xAF, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function supports the full console I/O code set.

See _cput_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

C/C++ Example
	float num = 12.70;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num, -34.0};
	   ...
	{
	   _vcput_script("\n\rX co-ordinate: "
	    __FLOAT_P _8 _2_Fix _Ralign 
	    _REP _12 " "
	    "\n\rY co-ordinate: "
	    __FLOAT _8 _2_Fix _Ralign, &params);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc = 12.70, yloc = -34.0;
	float *xy_params[2] = {&xloc, &yloc};
	{
	   char *xy_script = "\n\rX co-ordinate: "
	   	        __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   	        \n\rY co-ordinate: "
	   	        __FLOAT_P _8 _2_Fix _Ralign;
	   
	   pushds
	   pop es	 	/* ES=DS */

	   lea si,xy_script /* SI = offset of script */
	   mov di,xy_params /* DI = offset of param list */
	   vcput_script();    /* display x,y coordinates */
	   ...
	}

Source file _SIOVCPT.ASM ASM equiv CPUT_SCRIPT
See also
_cput_script, sio_addr, _vcget_script, _vhput_script, _vput_script, _vsput_script

_vget_script


Descrip
Reads and interprets input from STDIN using an input script and a pointer to a parameter list.

Syntax
#include <script.h>
int _vget_script(unsigned int count, const char *inscript, void *paramlist);

Returns
0 if the input was successfully read using the input script.
s_status final script status (error code is SE_OK)

1 if end-of-input was encountered before the input script could be fully processed.
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
s_status final script status (error code indicates error type)
Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads keyboard data into a temporary buffer using the _get_str function or its equivalent and interprets the input string as specified in the input script (inscript). No more than count characters or a single line of text is read (whichever is encountered first). Characters are echoed to the screen unless STDIN has bee redirected. The input data is interpreted as specified in inscript and the resulting values are stored as specified by the parameter list (paramlist). This function provides the same functionality as _get_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. 1 is returned if end-of-input was encountered before inscript could be fully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Input from STDIN is always processed sequentially, a character at a time, beginning with the first input character, as specified in inscript. Under no condition is more than one line or more than count characters read from STDIN to satisfy the script.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-input is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-input was encountered.

External parameters to inscript are passed via paramlist, which must be a structure containing the same argument list data which would follow inscript if _get_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

See _get_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

The following input script reads two float values from the keyboard (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	float num;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num};
	   ...
	{
	   _put_str("\n\rInput X,Y coordinates: ");
	   _vget_script(126,__FLOAT_P _Nolimit _2 _Calign_Exp 
	   _SKPCHR ","
	   __FLOAT _Nolimit _2 _Calign_Exp, &params);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc, yloc;
	float *xy_params[2] = {&xloc, &yloc};
	   ...
	{
	   char  str[] = "\n\rInput X,Y coordinates: ";
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp 
	   	        _SKPCHR ","
	   	        __FLOAT_P _Nolimit _2 _Calign_Exp;
	   ...
	   pushes
	   pop ds
	   mov cx,126	/* CX = max num of input chars */
	xy_read:
	   lea si,str	/* SI -> message */
	   put_str();
	   lea si,xy_script/* SI = offset of script */
	   mov di,xy_params /* DI = offset of params list */
	   vget_script();   /* read x,y coordinates */
	    je ok
	    ja again
	   jmp xy_read	    /* error, invalid input */
	again:	  /* error, insufficient input */
	   jmp xy_read	
	ok:... 	 	/* successful, continue */
	}

Source file _SIOVDGT.ASM ASM equiv GET_SCRIPT
See also
_get_script, _get_str, sio_addr, _vcget_script, _vhget_script, _vsget_script, _vput_script

_vhget_script


Descrip
Reads and interprets input from a file or device using an input script and a pointer to a parameter list.

Syntax
#include <script.h>
int _vhget_script(int handle, int *count, const char *inscript, void *paramlist);

Returns
0 if the input was successfully read using the input script.
count number of characters read from handle
s_status final script status (error code is SE_OK)

1 if end-of-file was encountered before the input script could be fully processed.
count number of characters read from handle
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
count number of characters read from handle
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function reads ASCII data into a temporary buffer from the file or device associated with handle and interprets that data as specified in the input script (inscript). As values are read from the input data, they are stored as specified by the parameter list (paramlist). This function provides the same functionality as _hget_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. 1 is returned if end-of-file was encountered before inscript could be fully processed. -1 is returned if an error occurred. count always indicates the number of characters actually read. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

Input data is always processed sequentially, a character at a time. If handle is associated with a file, then input data is read starting at the current file pointer position. On return, the file pointer points past the last character actually processed or interpreted by the input script (NOT the last character read). If handle is associated with a character device (e.g., CON), then data which is read from the device but not processed by the script is discarded. Note that multiple lines of input may be processed for a single input script if STDIN is specified as the input device.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-file is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-file was encountered.

External parameters to inscript are passed via paramlist, which must be a structure containing the same argument list data which would follow inscript if _hget_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

WARNING! This function uses approximately 250 bytes of stack space.

See _hget_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

The following input script reads two float values from a handle (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	float num;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num};
	   ...
	{
	   int count;
	   _vhget_script(handle, &count, 
	   __FLOAT_P _Nolimit _2 _Calign
	   _SKPCHR ","
	   __FLOAT _Nolimit _2 _Calign, &params);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc, yloc;
	float *xy_params[2] = {&xloc, &yloc};
	{
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp
	   _SKPCHR ","
	   __FLOAT_P _Nolimit _2 _Calign_Exp;
	   int handle;/* specify handle of device to read */
	   ...
	   pushds
	   pop es	 	/* ES = DS */   
	xy_read:
	   lea si,xy_script /* SI -> script string */
	   mov di,xy_params /* DI -> parameter list */
	   mov bx,handle/* BX = DOS file handle */
	   vhget_script();   /* read x,y coordinates,
	   	  	 	   CX = num char read */
	    je ok
	    ja again
	   ... 	 	/* error, invalid input */
	   jmp xy_read	    
	again:/* error, insufficient input */
	      jmpxy_read	
	ok:... 	 	/* successful, continue */
	}

Source file _SIOVHGT.ASM ASM equiv HGET_SCRIPT
See also
_hget_script, _hget_str, sio_addr, _vcget_script, _vhget_script, _vhput_script, _vsget_script

_vhput_script


Descrip
Uses an output script and a pointer to a parameter list to write data to a file or device.

Syntax
#include <script.h>
int _vhput_script(int handle, int *count, const char *outscript, void *paramlist);

Returns
0 if the output script was successfully processed.
count total number of characters written
s_status final script status (error code is SE_OK)
1 if an error occurred after output data was partially written to handle.
count number of characters actually written
s_status final script status (error code indicates error type, which may be SE_EOF)

-1 if an error occurred before any writes were performed.
count zero
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to the file or device associated with handle. This function provides the same functionality as _hput_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. 1 is returned if an error occurred during the processing of the script after some output data was written to handle. -1 is returned if an error occurred before any data could be written to handle. count always indicates the number of characters actually written. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

If s_status.ecode equals SE_DOS on return, then a DOS error occurred and the DOS error code is contained in e_code. A value of SE_EOF is returned in s_status.ecode if the disk is full or if a Ctrl-Z is written to a "cooked mode" character device (such as STDOUT) with additional output characters following the Ctrl-Z character. The SE_EOF condition is possible only if the return value is 1.

If handle is associated with a file, output data is written to the file starting at the current file pointer position. The file pointer is advanced past the last character written. 0 is returned immediately if processing of outscript does not require any characters to be written; no write is performed since this would cause DOS to truncate the file at the current input pointer position.

External parameters to outscript are passed via paramlist, which must be a structure containing the same argument list data which would follow outscript if _hput_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes. (The _BEL, _BS, _TAB, _LF, and _CR codes may only be used if STDOUT is specified as the output device).

See _hput_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

C/C++ Example
	float num = 12.70;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num, -34.0};
	   ...
	{
	   int count;
	   _vhput_script(1,&count,"\n\rX co-ordinate: "
	      __FLOAT_P _8 _2_Fix _Ralign 
	      _REP _12 " "
	   "\n\rY co-ordinate: "
	   __FLOAT _8 _2_Fix _Ralign, &params);
	   /* output x,y coordinates to STDOUT */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc = 12.70, yloc = -34.0;
	float *xy_params[2] = {&xloc, &yloc};
	   ...
	{
	   char xy_script[] = "\n\rX co-ordinate: "
	   __FLOAT_P _8 _2_Fix _Ralign _REP _12
	   \n\rY co-ordinate: "
	   __FLOAT_P _8 _2_Fix _Ralign;

	   ... 
	   mov bx,1	/* BX = standard out */
	   pushds
	   pop es	 	/* ES = DS */
	   lea si,xy_script/* SI = offset script string */
	   mov di,xy_param/* DI = offset param list */
	   vhput_script();    /* output x,y coordinates,
	   	  	 	   CX = num char written */
	   ...
	}

Source file _SOIVHPT.ASM ASM equiv HPUT_SCRIPT
See also
_hput_script, _hput_str, sio_addr, _vcput_script, _vhget_script, _vput_script, _vsput_script

_vput_script


Descrip
Uses an output script and a pointer to a parameter list to write data to STDOUT.

Syntax
#include <script.h>
int _vput_script(const char *outscript, void *paramlist);

Returns
0 if the output script was successfully processed.
s_status final script status (error code is SE_OK)

-1 if an error occurred.
s_status final script status (error code indicates exact error)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to STDOUT. This function provides the same functionality as _put_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.

If s_status.ecode equals SE_DOS on return, then a DOS error occurred and the DOS error code is contained in e_code. s_status.ecode is set to SE_EOF if the disk is full or if a Ctrl-Z is written to a "cooked mode" character device (such as STDOUT) with additional output characters following the Ctrl-Z character.

External parameters to outscript are passed via paramlist, which must be a structure containing the same argument list data which would follow outscript if _put_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes (except for _BEL, _BS, _TAB, _LF, and _CR, which are correctly interpreted by STDOUT).

See _put_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

C/C++ Example
	float num = 12.70;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num, -34.0};
	   ...
	{
	   _vput_script("\n\rX co-ordinate: "
	    __FLOAT_P _8 _2_Fix _Ralign
	    _REP _12 " "
	    "\n\rY co-ordinate: "
	    __FLOAT _8 _2_Fix _Ralign, &params);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc = 12.70, yloc = -34.0;
	float *xy_params[2] = {&xloc, &yloc};
	   ...
	{
	char xy_script[] = "\n\rX co-ordinate: "
	   __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   \n\rY co-ordinate: "
	   __FLOAT_P _8 _2_Fix _Ralign;
	   ... 
	   pushds
	   pop es	 	/* ES=DS (params on stack) */
	   lea si,xy_script /* SI = offset script string */
	   mov di,xy_params /* DI = offset param list */
	   vput_script();	/* output x,y coordinates */
	   ...
	}

Source file _SIOVDPT.ASM ASM equiv PUT_SCRIPT
See also
_put_script, _put_str, sio_addr, _vcput_script, _vget_script, _vhput_script, _vsput_script

_vsget_script


Descrip
Reads and interprets an ASCIIZ string using an input script and a pointer to a parameter list.

Syntax
#include <script.h>
int _vsget_script(int *count, char *string, const char *inscript, void *paramlist);

Returns
0 if the input was successfully read using the input script.
count number of characters read from string
s_status final script status (error code is SE_OK)

1 if end-of-string was encountered before the input script could be fully processed.
count number of characters read from string
s_status final script status (error code is SE_EOF)

-1 if an error occurred.
count number of characters read from string
s_status final script status (error code indicates error type)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an ASCIIZ input string (string) as specified in the input script (inscript). As values are read from string they are stored as specified by the parameter list (paramlist). This function provides the same functionality as _sget_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. 1 is returned if end-of-string was encountered before inscript could be fully processed. -1 is returned if an error occurred. count always indicates the number of characters actually read. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any.
The ASCIIZ data in string is always processed sequentially, a character at a time, beginning with the first byte in string, as specified in inscript. Under no condition is any data processed past the end of string.

Technically, a return value of 1 is an error return. However, the programmer must determine if this condition is a true error. Since end-of-string is essentially field underflow of all remaining fields, the application may wish to treat a return value of 1 as a normal return condition. The value returned in s_status.paramcnt may be used to determine how many parameters were successfully processed from the parameter list before end-of-string was encountered.

External parameters to inscript are passed via paramlist, which must be a structure containing the same argument list data which would follow inscript if _sget_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in inscript (ASCII values 0x10-0x7E and 0x80-0xDF) are matched against input characters as they are encountered. If character validation is enabled, then non-interpreted characters MUST match input characters or an invalid character error is returned. Otherwise, non-interpreted characters are treated as optional matching characters.

Script codes in inscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, and input data synchronization.

See _sget_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

The following input script reads two float values from a string (XLOC and YLOC). Each value is read with 2 digits of precision to the right of the decimal point. The values are correctly read whether or not space characters are typed before, after, or between the values, and whether or not a comma character properly separates the values. Also, the values may be entered with any number of digits to the right of the decimal point, and they may be entered in exponential or non-exponential format. All of these cases are properly handled by the simple input script shown below.

C/C++ Example
	float num;
	struct {
	   float *xloc;
	   float yloc;
	} params = {&num};
	   ...
	{
	   int count;
	   _vsget_script(&count, "1.2345, 12.34"
	   __FLOAT_P _Nolimit _2 _Calign_Exp
	      _SKPCHR ","
	     __FLOAT _Nolimit _2 _Calign_Exp, &params);
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc, yloc;
	float *xy_params[2];
	   ...
	{
	   char instr[] = "1.234, 1.655";
	   char xy_script[] = __FLOAT_P _Nolimit _2 _Calign_Exp
	   	      _SKPCHR ","
	   	     __FLOAT_P _Nolimit _2 _Calign_Exp;
	   ...   
	   lea ax,instr
	   mov bx,ss	/* BX:AX -> string */
	   pushds
	   pop es	 	/* DS=SS (params on stack) */
	   lea si,xy_script/* SI = offset script string */
	   mov di,xy_params /* DI = offset param list */
	   vsget_script();   /* read x,y coordinates,
	   	  	 	   CX = num char read */
	   ...
	}

Source file _SIOVSGT.ASM ASM equiv SGET_SCRIPT
See also
_sget_script, sio_addr, _vcget_script, _vget_script, _vhget_script, _vsput_script

_vsput_script


Descrip
Uses an output script and a pointer to a parameter list to write data to an ASCIIZ string.

Syntax
#include <script.h>
int _vsput_script(int *count, int size, char *buffer, const char *outscript, void *paramlist);

Returns
0 if the output script was successfully processed.
buffer resulting ASCIIZ string
count length of ASCIIZ string written to buffer
s_status final script status (error code is SE_OK)

-1 if an error occurred.
buffer partial ASCIIZ string
count length of partial ASCIIZ string written to buffer
s_status final script status (error code indicates error type, which may be SE_EOF)

Notes

See the Scripted I/O Function-to-Code Cross Reference

This function interprets an output script (outscript) using the specified parameter list (paramlist) and writes the specified data to buffer in ASCIIZ format. This function provides the same functionality as _sput_script except that it accepts a pointer to a list of parameters instead of an argument list.

0 is returned if the script was successfully processed. -1 is returned if an error occurred. The final script status is returned in s_status, with s_status.ecode indicating the error type, if any. count indicates the length of the output ASCIIZ string excluding the terminal NULL.

If s_status.ecode equals SE_EOF on return, then the end of buffer was encountered before outscript could be fully processed.

The resulting ASCIIZ string is never more than size-1 bytes in length (excluding the terminal NULL).

External parameters to outscript are passed via paramlist, which must be a structure containing the same argument list data which would follow outscript if _sput_script were called instead of this function. (See the Scripted I/O technical notes for an explanation of how these parameter lists are created.)

By default, pointers in paramlist are near pointers (offsets) in small data models and far pointers (segment:offset pairs, offset first) in large data models. Pointers are expected in the parameter list whenever script codes are encountered which end with ..._P, or whenever a string or an explicit address is expected (strings are always referenced via pointers). A near or far pointer type may be explicitly specified for a specific parameter by using a script code which ends with ..._N or ..._F, respectively.

The near pointer segment is assumed to be DGROUP (global or static non-far data). The near pointer override cannot be used in 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.

Non-interpreted characters in outscript (ASCII values 0x10-0x7E and 0x80-0xDF) are written to the display as they are encountered using the current text attribute.

Script codes in outscript (ASCII values 0x00-0x0F, 0x7F, and 0xE0-0xFF) are interpreted and their associated functions are performed as they are encountered. Script codes are used to specify options for scripting flow control, formatted data output, data synchronization, and console I/O.

This function does NOT support console I/O script codes.

See _sput_script (or the technical notes) for a list of valid script codes for this function. See Appendix H for a complete scripted I/O function-to-code cross reference.

C/C++ Example
	float num = 12.70;
	struct param_list {
	   float *xloc;
	   float yloc;
	} params = {&num, -34.0};
	   ...
	{
	   int count;
	   char buffer[126];
	   _vsput_script(&count, sizeof(buffer), buffer,
	    "\n\rX co-ordinate: "
	    __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	    "\n\rY co-ordinate: "
	   __FLOAT _8 _2_Fix _Ralign, &params);
	   /* output result to buffer */
	   ...
	}

Inline Assembly Example
	#include <inline.h>
	float xloc = 12.70, yloc = -34.0;
	float *xy_params[] = {&xloc, &yloc};

	{     
	   char buffer[126];
	   char xy_script[] = "\n\rX co-ordinate: "
	   	     __FLOAT_P _8 _2_Fix _Ralign _REP _12 " "
	   	     \n\rY co-ordinate: "
	   	     __FLOAT_P _8 _2_Fix _Ralign;
	   ... 
	   mov cx,126	/* CX = size of buffer */
	   mov bx,ss
	   lea ax,buffer /* BX:AX -> output buffer */
	   pushss
	   pop es	 	/* ES=SS (params on stack) */
	   lea si,xy_script /* SI = offset script string */
	   lea di,xy_params /* DI = offset param list */
	   vsput_script();    /* output result to buffer, 
	   	  	 	   CX = num char written */
	   ...
	}

Source file _SIOVSPT.ASM ASM equiv SPUT_SCRIPT
See also
sio_addr, _sput_script, _vcput_script, _vhput_script, _vput_script, _vsget_script