ScriptEase Standard Library Extensions

VERSION_MAJOR

2

VERSION_MINOR

10

VERSION_STRING

"GA"

_DOS_

1

_DOS32_

1

_OS2_

1

_WINDOWS_

1

_WIN32_

1

_NWNLM_

1

_UNIX_

1

_MAC_

1

_SHELL_

1

_NTCON_

1

_NTWIN_

1

_95CON_

1

_95WIN_

1

BIG_ENDIAN

1 (i.e. TRUE) if processor stores high-byte first (e.g. Motorolla)

BIG_ENDIAN

0 (i.e. FALSE) if processor stores low-byte in low_memory (e.g. Intel)

DESCRIPTION

Global variable to specify ScriptEase-data to memory-data conversion.

SYNTAX

bool _BigEndianMode;

COMMENTS

This is a global variable set to specify if data read or written by the fread(), fwrite(), BLObGet(), BLObPut(), peek(), poke(), PMpeek(), PMpoke(), or DynamicLink() functions is stored in memory in a Big-Endian or Little-Endian format. This defaults to BIG_ENDIAN.

SEE ALSO

BLObGet(), BLObSize(), fread(), fwrite(), peek(), poke(), PMpeek(), PMpoke(), DynamicLink()

DESCRIPTION

Read data from specified location of a Binary Large Object (BLOb).

SYNTAX

byte BLObGet(blob BLObVar, int offset, int DataType=UWORD8)

int BLObGet(blob BLObVar, int offset, int DataType)

float BLObGet(blob BLObVar, int offset, int DataType)

byte[] BLObGet(blob BLObVar, int offset, int bufferLen)

struct BLObGet(blob BLObVar, int offset,
struct DataStructureDefinition)

COMMENTS

This is the companion function to BLObPut(). BLObGet() retrieves data of specified size from a BLOb and returns and appropriate variable. Valid data types are: UWORD8, SWORD8, UWORD16, SWORD16, UWORD24, SWORD24, UWORD32, SWORD32, FLOAT32, FLOAT64, FLOAT80 See fread() in the Standard Library (Chapter 6) for more information on these DataType values.

RETURNS

Returns a variable containing the data retrieved.

SEE ALSO

BigEndianMode, BLObPut(), BLObSize(), fread()

DESCRIPTION

Write data into specified location of a Binary Large Object (BLOb).

SYNTAX

int BLObPut(blob BLObVar[, int offset], Var v, int DataType)

int BLObPut(blob BLObVar[, int offset], byte[] buffer, int bufferLen)

int BLObPut(blob BLObVar[, int offset], struct SrcStruct,
struct DataStructureDefinition)

COMMENTS

This function, along with BLObGet(), allows for direct access to memory within a variable that may be viewed as a packed structure. Data can be placed at any location within a BLOb. If DataType is not the length of a byte buffer then it must be one of these types:

UWORD8, SWORD8, UWORD16, SWORD16, UWORD24, SWORD24, UWORD32, SWORD32, FLOAT32, FLOAT64, FLOAT80

See fread() in the Standard Library (Chapter 6) for more information on these DataType values.

If offset is not supplied, then the data will be put at the end of the existing blob, or at 0 if the blob is not defined yet.

The Data in v will be converted to the specified DataType and then copied into those bytes.

RETURNS

Returns the byte offset for the next byte following the section where data was just put; in other words, if the data were put at the end of the BLOb, then this returns the sizeof(BLOb).

SEE ALSO

BigEndianMode, BLObGet(), BLObSize(), fread(), fwrite()

EXAMPLE

If you were sending a pointer to data in an external C library, and you knew the library expected the data in a packed DOS structure of the form:

struct foo {

signed char a;

unsigned int b;

double c;

};

If you were building this structure from three corresponding variables, then such a building function may look like this:

BuildFooBlob(a,b,c)

{

offset = BLObPut(foo, 0, a, SWORD8);

offset = BLObPut(foo, offset, b, UWORD16);

BLObPut(foo, offset, c, FLOAT64);

return foo;

}

or, because if offset is not supplied then data is put at the end:

BuildFooBlob(a,b,c)

{

BLObPut(foo, a, SWORD8);

BLObPut(foo, b, UWORD16);

BLObPut(foo, c, FLOAT64);

return foo;

}

DESCRIPTION

Determine size of a Binary Large Object (BLOb).

SYNTAX

int BLObSize(blob BLObVar[, SetSize])

int BLObSize(int DataType)

int BLObSize(int bufferLen)

int BLObSize(struct DefinitionStructure)

COMMENTS

Gets the size of a blob. Optionally, can set the size of a BLOb, even create a BLOb, if the SetSize value is supplied.

If using DataType, bufferLen, or DefinitionStructure this function returns the size of the BLOb that would contain the type of data item used in the BLObGet() or BLObPut() call, where this is the type used for converting ScriptEase data to/from a BLOb.

MODIFIES

If SetSize is supplied then alters BLObVar to be SetSize, even creating or making BLObVar if it is not already a BLOb.

RETURN

Returns the number of bytes in BLObVar. This is the same value you'd get from "1+GetArraySpan(BLObVar)". If SetSize is supplied then will return SetSize.

SEE ALSO

BLObGet(), BLObPut(), GetArraySpan(), SetArraySpan()

DESCRIPTION

Test if running from a ScriptEase /BIND executable.

SYNTAX

bool Bound()

RETURN

Return TRUE if running from ScriptEase /BIND executable, else return FALSE.

EXAMPLE

This code in TEST.CMM will print the digit 0 if run as "CEnviTEST.CMM", but if the same file is run from TEST.EXE after "ScriptEase /BIND=TEST.EXE TEST.CMM" the output is the
digit 1:

printf("Bound() = %d", Bound());

DESCRIPTION

Return numerical value as represented by a byte.

SYNTAX

byte byte(var v)

RETURN

Returns v as represented by a byte.

SEE ALSO

integer(), float()

DESCRIPTION

Determine dimension of variable data.

SYNTAX

int DataDimension(var)

COMMENTS

Determine the dimensionality of a known data type, where 0 is a datum, 1 is a 1-dimensional array, 2 is a 2-dimensional array, and so on. This function is useful for determining how to treat input parameters for a function that takes multiple parameter types.

RETURN

Return integer for dimension of this variable; 0 is datum; 1 is array; etc...

SEE ALSO

DataType(), defined()

DESCRIPTION

Determine data type of a variable.

SYNTAX

int DataType(var)

COMMENTS

Determine the type of data for a variable. This function is useful for determining how to treat input parameters for a function that takes multiple parameter types. The data type returned will be on of the following pre-#defined values:

CMM_UNKNOWN data type has not been determined;

CMM_STRUCT var is a structure variable

CMM_BYTE Byte (if 1 == DataDimension() maybe a string)

CMM_INT integer value

CMM_FLOAT floating-point value

Note that the above values are sequential so that the following function would return TRUE if a value is numeric (CMM_BYTE, CMM_INT, or CMM_FLOAT) and FALSE if it is not numeric:

IsItNumeric(value)

{

return(CMM_BYTE <= DataType(value) );

}

RETURN

Data type CMM_UNKNOWN, CMM_STRUCT, CMM_BYTE, CMM_INT, or CMM_FLOAT

SEE ALSO

DataDimension(), defined()

EXAMPLE

The following function, PrintValue(), would print the single value passed to it in a native format, whether it be a byte, integer, float, or string:

PrintValue(value) //printf() value in native format

{

// default print message if bad value

FormatString = "INVALID VALUE\a";

switch(DataDimension(value) ) {

case 0: // 0-dimensional array; i.e., datum

switch(DataType(value) ) {

case CMM_BYTE:

FormatString = "%c";

break;

case CMM_INT:

FormatString = "%d";

break;

case CMM_FLOAT:

FormatString = "%f";

break;

default:

// other types not recognized

// for PrintValue()

break;

}

break;

case 1:

// 1-dimensional array; only recognizes string

if (CMM_BYTE == DataType(value) )

FormatString = "%s";

default: // dimensions above 1 are unrecognized

break;

}

printf(FormatString,value);

}

DESCRIPTION

Test if variable has been defined.

SYNTAX

bool defined(var v)

COMMENTS

Test whether a value has a data definition. This is useful to test if individual elements of a structure are defined.

RETURN

Return TRUE if v is defined, else return FALSE.

SEE ALSO

DataDimension(), DataType(), undefine()

DESCRIPTION

Search directory listing for a file specification.

SYNTAX

struct[] Directory([, string SearchSpec[, bool RecurseSubdirectories [, int IncludeAttrib[, int RequiredAttrib]]]])

COMMENTS

Search through the directory file structure to get files matching the SearchSpec path specification, that match the SearchSpec file specification and include all normal files and those files with one of the Attrib attribute bits set. This function returns the number of files found and creates a Found structure array containing data found for each of the file matches.

SearchSpec is any valid file specification, including wildcards and drives and/or paths, that matches the filespec parameters of the operating system. If this parameter is not supplied then it defaults to match all files in the current directory.

RecurseSubdirectories is TRUE if you want to search recursively through subdirectories, and FALSE to only search the directory specified in SearchSpec. If this parameter is not supplied then its default is FALSE.

IncludeAttrib is an OR of flags specifying which files to match based on file flags. If a file has a flag set, and that flag is not specified in Attrib, then that file will not be returned as a match. Flags that do not apply to the operating system are ignored. If 0 is specified here then only matches normal files that have no special attributes set. If this parameter is not specified then it defaults to: (FATTR_RDONLY| FATTR_SUBDIR|FATTR_ARCHIVE).

The defined flags for Attrib are:

FATTR_RDONLY Read-only file

FATTR_HIDDEN Hidden file

FATTR_SYSTEM System file

FATTR_SUBDIR Directory

FATTR_ARCHIVE Archive file

RequiredAttrib is an OR of the same flags as defined under IncludeAttrib. In this case, all files will be excluded from the search that do not have all of the RequiredAttrib flags set. If no flags are supplied it defaults to 0.

RETURN

If no files match SearchSpec, then returns NULL, else returns an array of structures containing the following members (date-time numbers are all in the format returned by the time() function--see time library--and those fields that do not apply to this operating system are duplicated from those that do apply):

.name Full file name, including the SearchSpec path.

.attrib OR of file flags, as defined above in IncludeAttrib

.size Size of file, in bytes

.Access Date and time of last file access

.Write Date and time of last write to file

.Create Date and time of file creation

SEE ALSO

FullPath(), SplitFileName()

EXAMPLE

This routine would list all files in the current directory, except for subdirectory entries:

ListDirectory(FileSpec) // list all files except

// directory entries

{

FileList = Directory(FileSpec,False,~FATTR_SUBDIR)

if (NULL == FileList)

printf("No files found for search spec \"%s\".\n",

FileSpec);

else {

FileCount = 1 + GetArraySpan(FileList);

for (i = 0; i < FileCount; i++)

printf("%s\tsize = %d\tCreate date/time = %s\n",

FileList[i].name, FileList[i].size,

ctime(FileList[i].Create) )

}

}

DESCRIPTION

Return numerical value as represented by a floating-point number.

SYNTAX

float float(var v)

RETURN

Returns v as represented by a floating-point value.

SEE ALSO

byte(), float()

DESCRIPTION

Convert partial path specification to full path name.

SYNTAX

string FullPath(string PathSpec)

COMMENTS

This function converts PathSpec, which should be a valid file-system path specification, into an absolute path name. Absolute path will correspond to the operating system's conventions.

RETURN

Return string containing the full path specification, or NULL if PathSpec was invalid.

SEE ALSO

Directory(), SplitFileName()

EXAMPLE

The following example function returns the full specification of the current directory:

// return full specification for the current directory

CurDir()

{

return FullPath(".")

}

This routine works in DOS and OS/2 to test whether a drive letter is valid:

ValidDrive(DriveLetter) // return TRUE if DriveLetter is

// valid, else FALSE {

sprintf(CurdirSpec,"%c:.",DriveLetter)

return (NULL != FullPath(CurdirSpec) )

}

DESCRIPTION

Call a function by name.

SYNTAX

var function(string FunctionName[,...])

COMMENTS

This calls the function named FunctionName with all following arguments, and it returns whatever FunctionName(...) returns.

RETURN

Returns whatever FunctionName(...) will return.

MODIFIES

Modifies whatever FunctionName(...) will modify.

EXAMPLE

The famous "hello world" program line could be written in any of these three ways:

printf("hello world");

function("printf","hello world");

function("function","function","printf","hello world");

DESCRIPTION

Determine size of an array.

SYNTAX

int GetArraySpan(var[] array[ ,int MinIndex])

COMMENTS

Get the maximum and minimum indices for array.

RETURN

Return the Maximum index for this array. If MinIndex is passed in then it will be set to the minimum index, which will be zero or less.

SEE ALSO

BLObSize(), DataDimension(), SetArraySpan()

EXAMPLE

This script demonstrates GetArraySpan:

string = "I do not like green eggs and ham."

gas = GetArraySpan(string);

printf("string = %s\nGetArraySpan(string) = %d\n"

"string[GetArraySpan(string)] = %d\n"

"string[GetArraySpan(string)-1] = %c\n"

"strlen(string) = %d\n",

string, gas, string[gas], string[gas-1], strlen(string));

getch();

and has the following output:

string = I do not like green eggs and ham.

GetArraySpan(string) = 33

string[GetArraySpan(string)] = 0

string[GetArraySpan(string)-1] = .

strlen(string) = 33

GetArraySpan() returns the same value as strlen() does because of the NULL byte that terminates the string. The NULL byte is at string[33]; so GetArraySpan() returns 33, the highest index in the array. Since the string contains 33 elements (at indexes 0-32) strlen also returns 33.

This function clips off any array value below zero (negative indices) and returns the number of elements in the new array:

// clip off negative indexes in array, and return

// the number of elements in the truncated array

AbsElementCount(array)

{

SetArraySpan(array,0,GetArraySpan(array));

return (1 + GetArraySpan(array));

}

DESCRIPTION

Get a name list of all the members of a structure.

SYNTAX

string[] GetStructureMembers(structure StructureVariable, [bool IncludeUndefinedMembers])

COMMENTS

This function will return an array of strings containing the name of each member of the structure variable StructureVariable.

IncludedUndefinedMembers is a boolean TRUE if you want to return members that are not defined. If boolean FALSE then only return members that have defined data types (i.e. defined(member)). If this parameter is not supplied then default to FALSE and only return defined members.

The final member of the array returned is always NULL. If StructureVariable is not defined, is not a structure of dimension 0, or contains no member to be displayed then this will return only one element in the array, which will be NULL.

RETURN

Return array of strings for each member of structure. Final member is NULL.

EXAMPLE

The following example code:

Point.row = 5;

Point.col = 8; Point.height;

PrintAllStructureMembers(Point);

PrintAllStructureMembers(StructVar)

{

printf("Structure Members:\n");

MemberList = GetStructureMembers(StructVar);

for (i = 0; MemberList[i]; i++)

printf(" %s\n",MemberList[i]);

}

would produce this output:

Structure Members:

row

col

DESCRIPTION

Return numerical value as represented by an integer.

SYNTAX

int integer(var v)

RETURN

Returns v as represented by an integer.

SEE ALSO

byte(), integer()

DESCRIPTION

Interpret ScriptEase code or source file.

SYNTAX

int Interpret(string Code[, int InterpretFlags[, string ErrorString])

COMMENTS

Code is a string consisting of the script to be interpreted and any parameters it takes. InterpretFlags is a bitwise or of the following choices, and 0 (no flags) if not supplied. The flags indicate to the computer how to interpret the Code parameter. If they are not supplied, then the computer will parse the string and try to figure out the most appropriate way to interpret it. To avoid misinterpretation, use the following flags to define its behavior:

INTERP_FILE Code must be name of ScriptEase source file, followed by any arguments

INTERP_TEXT Code is not a file name, but is straight ScriptEase source; no arguments

INTERP_LOAD Load code into same function and variable space, i.e. at the same level as, the code that is calling Interpret(). All functions, local and global variables will be supplied to the code being called, which can modify and use them. If the code being called has similarly named functions or variables as the calling code, the functions in the called code will replace those in the calling code.

INTERP_NOINHERIT_LOCAL Local variables (variables in the current function from which interpret() is called) will not become inherited as global variables in the interpreted code.

INTERP_NOINHERIT_GLOBAL Global variables (variables used externally to any function) will not become inherited as global variables in the interpreted code.

Note that INTERP_FILE and INTERP_TEXT are mutually exclusive. If neither are supplied then Intepret() examines Code and decides if it looks like a file or like pure code.

If there is an error handling the Interpret() function, the variable ErrorString will be set to a string describing the error (otherwise it will be NULL).

You cannot use the Interpret function on ScriptEase scripts that have been turned into executable with the /BIND option.

RETURN

Return -1 if error, else return the return value of the code being interpreted.

NOTE

This function cannot be called from code that has been bound with ScriptEase' /BIND feature.

EXAMPLE

The following example code:

Interpret(`puts("Hello world!")`, INTERP_TEXT);

would produce this output:

Hello world!

Similarly, the following code:

Interpret("CmmEdit C:\autoexec.bat", INTERP_FILE);

will open the script CmmEdit (the text editor created in the tutorial pages) with the file autoexec.bat loaded.

DESCRIPTION

Return a formatted string.

SYNTAX

rsprintf(FormatString/*,args*/)

COMMENTS

The rsprintf() function is a form of the printf function. It allows you to insert formatted strings directly into a document. For example, if in a script you had a line:

printf("%s has seen %s %d times.\n", name, movie,

timesSeen);

and you wanted to pass the resulting string as a parameter to a function, you could do it like this:

func(rsprintf("%s has seen %s %d times.\n", name,

movie, timesSeen));

The following two lines of code achieve the same result, i.e. create a string named word that contains the string "Who is #1?":

word = rsprintf("Who is #%d?", 3-2);

sprintf(word, "Who is #%d?", 3-2);

RETURNS

A string formatted according to the parameters passed.

SEE ALSO

printf(), sprintf(), rvsprintf()

rvsprintf

DESCRIPTION

Return formatted output using arg_list.

SYNTAX

int vsprintf(string format, blob valist)

COMMENTS

This is similar to sprintf() except that it takes a variable argument list (see va_start()) and returns the string directly, rather than storing it in a string buffer. See sprintf() for more details.

RETURNS

Returns the string specified by the format string, or EOF if there was an error.

SEE ALSO

sprintf(), va_arg(), va_end(), va_start()

DESCRIPTION

Clear screen.

SYNTAX

void ScreenClear()

COMMENTS

Clears the visible area of the screen.

DESCRIPTION

Get or set cursor position in the visible screen.

SYNTAX

struct ScreenCursor([int col[, int row]])

COMMENTS

Sets the column if col is supplied, and the row if row is supplied. Positions begin at zero and go to ScreenSize().col-1 and ScreenSize().row-1.

RETURNS

Returns the cursor position after this call in the two structure elements: .col .row

EXAMPLE

This example will draw a simple border of asterisks all around the screen (only draws one above the bottom row because drawing the lower-right corner causes the screen to scroll):

DrawAsteriskBorder()

{

size = ScreenSize();

ScreenClear();

// draw top border

ScreenCursor(0,0);

for (col = 0; col < size.col; col++)

putchar(`*');

// draw bottom border

ScreenCursor(0,size.row-2);

for (col = 0; col < size.col; col++)

putchar(`*');

// draw left and right borders

for (row = 0; row < size.row - 1; row++) {

ScreenCursor(0,row);

putchar(`*');

ScreenCursor(size.col-1,row);

putchar(`*');

}

}

DESCRIPTION

Get the height and width of the screen.

SYNTAX

struct ScreenSize()

COMMENTS

Gets the size of the visible screen in rows and columns.

RETURN

Returns the screen size as a structure with the two elements:

.col screen width, in characters

.row screen height, in characters

DESCRIPTION

Set size of an array.

SYNTAX

void SetArraySpan(var[] array[, int MinIndex], int MaxIndex)

COMMENTS

Grow or shrink the array to span from MinIndex to MaxIndex with the constraints: 0 <= MaxIndex, MinIndex <= 0. If MinIndex is not specified then it will be 0.

RETURN

None.

MODIFIES

array limits are altered.

SEE ALSO

BLObSize(), DataDimension(), GetArraySpan()

DESCRIPTION

Add character filter function to ScriptEase shell.

SYNTAX

void ShellFilterCharacter(string CharFltrFunction, bool AllKeys)

COMMENTS

When ScriptEase is running as a command shell (i.e., executed with no arguments), this allows you to install a function to be called when keystrokes are pressed. For example, the AUTOLOAD.CMM script that ships with ScriptEase uses this function to implement command-line history and file-name completion.

AllKeys specifies whether the function will be called for every keystroke, or just for keys that are not ordinary printable (isprint()) characters.

CharFltrFunction is the string name of a ScriptEase function of the type:

bool CharFltrFunction(string Command, int Position, int Key,
bool Extended, bool AlphaNumeric)

Command is the current string on the shell's command line. This is read/write, so you may change the command string during this function call.

Position is the current cursor position within the Command string. This may be altered during this function. Key is the key being pressed. This also may be altered. Set to 0 (zero) to ignore key input.

Extended is TRUE if this is an extended keyboard character (e.g., function keys, key combinations, etc...)

AlphaNumeric is TRUE if this is an alphabetic or numeric key (i.e., isalpha()).

CharFltrFunction returns TRUE if the command line must be redrawn, or the cursor position moved, based on the actions in this function.

RETURN

None.

DESCRIPTION

Add command filter function to ScriptEase shell

SYNTAX

void ShellFilterCommand(string CmdFltrFunction)

COMMENTS

When ScriptEase is running as a command shell (i.e., executed with no arguments), this allows you to install a function to be called when commands have been entered. For example, the AUTOLOAD.CMM script that ships with ScriptEase uses this function to implement some commands, such as CD and TYPE.

CmdFltrFunction is the string name of a ScriptEase function of the type:

void CmdFltrFunction(string Command)

Command is the current string on the shell's command line. This is read/write, so you may change the command string during this function call. The ScriptEase shell will execute this command after returning from this call. To prevent ScriptEase from executing any command (perhaps your filter handled the command internally) set Command to a zero-length string (e.g., Command[0]='\0', not Command="").

Before passing the command line to this filter function, ScriptEase will have stripped leading whitespace from the beginning and end of the command. Also, the redirection on a command line will not be seen by this function, because redirection is handled internally by ScriptEase. For example, if the command line string is "dir>dir.txt" then this function will only see the string "dir".

RETURN

None.

DESCRIPTION

Run an external executable.

SYNTAX

int spawn(int mode, string ExecutionCommandLine)

int spawn(int mode, string ExecutableSpec [, var arg1[, var arg2[,
var arg3[,...]]]])

int spawn(int mode, string ExecutableSpec[, string[] ArgStrings])

COMMENTS

This executes ExecutableSpec as a child process. This is more specific than the general standard library call "system()". ExecuteableSpec may be the name of a ScriptEase script, in which case the executable is understood to be the same version of ScriptEase as the one you're calling spawn from. ScriptEase scripts may be spawned as well as executables. Execute child program in one of these ways, depending on these pre-defined values of mode:

P_WAIT Wait for the child program to complete before continuing.

P_SWAP Like P_WAIT, but swap out ScriptEase to create more room for child process.

P_NOWAIT Continue to run program while child program runs.

P_OVERLAY This program exits and child program is executed in its place. In most C libraries this call requires an arg 0 to pass to the child, but in this library the ExecutableSpec is automatically passed as argument 0. Also, most libraries expect strings to be passed as the arguments, but ScriptEase will implicitly convert the arguments into strings before passing them on to the child process. You cannot spawn a script that has been bound with the ScriptEase /BIND function.

DOS P_WAIT , P_SWAP , or P_OVERLAY Searches for ExecutableSpec in the current directory then in the directories of the PATH environment variable. If there is no extension on ExecutableSpec it will search first for .COM then .EXE files. P_SWAP will free up as much memory as possible by swapping ScriptEase to EMS/XMS/INT15 memory or to disk (in TMP directory, else TEMP, else current directory) before executing the child process (thanks to Ralf Brown for his excellent spawn library).

If a batch file is being spawned, and if the environment variable COMSPEC_ENV_SIZE exists, then the command processor will be provided with this much memory for handling environment variables. If COMSPEC_ENV_SIZE does not exist then the command processor receives only enough memory for existing environment variables.

DOS32 P_WAIT Searches for ExecutableSpec in the current directory then in the directories of the PATH environment variable. If no extension on ExecutableSpec then will search for .COM then .EXE files. If a batch file is being spawned, and if the environment variable COMSPEC_ENV_SIZE exists, then the command processor will be provided with this much memory for handling environment variables. If COMSPEC_ENV_SIZE does not exist then the command processor receives only enough memory for existing environment variables.

OS/2 P_WAIT , P_NOWAIT Searches for ExecutableSpec in the current directory then in the directories of the PATH environment variable. If no extension on ExecutableSpec then will search for .COM then .EXE files.

WINDOWS P_WAIT , P_NOWAIT Successful P_NOWAIT return id is the window handle of the child process.

RETURN

Returns -1 for error and sets errno to identify the error. For success returns the exit code of the child process for P_WAIT, does not return for P_OVERLAY, else returns the an identifier of the child process.

SEE ALSO

system()

EXAMPLES

This example calls a mortgage program MORTGAGE.EXE which takes three parameters, initial debt, rate, and monthly payment, and returns number of months needed to pay the debt in its exit code:

months = spawn(P_WAIT,"MORTGAGE.EXE 300000 10.5 1000");

if (months < 0)

printf("Error spawning MORTGAGE\n");

else

printf("It takes %d months to pay off the mortgage\n",

months);

The parameters could also be passed to MORTGAGE.EXE as separate variables:

months = spawn(P_WAIT,"MORTGAGE.EXE",300000,10.5,1000);

The same arguments could be passed to MORTGAGE.EXE in a variable array, provided that they are all he same data type (in this case strings):

MortgageData[0] = "300000";

MortgageData[1] = "10.5";

MortgageData[2] = "1000";

ths = spawn(P_WAIT,"MORTGAGE.EXE",MortageData);

DESCRIPTION

Determine directory, name, and extension parts of a file specification.

SYNTAX

structure SplitFileName(string FileSpec)

COMMENTS

Splits the FileSpec into its various components that conform to the conventions of the operating system: dir, name, and ext, where:

. dir name of the directory, including leading and drive separator characters

. name root name of the file

. ext extension name of the file, including preceding dot (.)

All components are guaranteed to be non-NULL, and FileSpec can be reconstructed with this source statement:

FileSpec = strcat(strcat(dir,name),ext)

RETURN

Returns a structure with the dir, name, and ext member variables set to non-NULL strings.

SEE ALSO

Directory(), FullPath()

EXAMPLE

The following two lines show results from sample inputs to SplitFileName() (the second example applies to the file structure for DOS and OS/2):

// sets parts.dir="", parts.name="foo", parts.ext=""

parts = SplitFileName("foo")

// parts.dir="..\\", parts.name="*", parts.ext=".doc"

parts = SplitFileName("..\\*.doc")

DESCRIPTION

Access structure member by name.

SYNTAX

var StructureMember(structure StructureVariable, string MemberName)

COMMENTS

This function will act on a member of a structure by name. StructureVariable is a structure, and MemberName is the ascii string to represent the member. The variable returned by this function may be used as an lvar.

RETURN

Return variable for this structure member. May be used as a lvar.

EXAMPLE

The following example code:

Point.row = 5;

Point.col = 8;

could be replaced by this sample code:

StructureMember(Point,"row") = 5;

StructureMember(Point,"col") = 8;

DESCRIPTION

Suspend program execution for a specified amount of time.

SYNTAX

void Suspend(int milliSecondDelay)

COMMENTS

Your program may want to suspend itself for a limited time without abusing system resources, especially in multitasking systems. This function allows your program to use as little resources as possible for the length of this delay. Total millisecond accuracy is not guaranteed, but is only approximated according to the accuracy provided by the underlying operating system.

EXAMPLE

To suspend execution of your code for 1/2 second:

Suspend(500);

DESCRIPTION

Make a variable undefined.

SYNTAX

void undefine(var v)

COMMENTS

Clear this variable data. Further calls to defined(v) will return false. If used on an element of an array, then this only has effect if the element of v is a structure, in which case it undefines all elements of the structure.

RETURN

None.

MODIFIES

v becomes undefined.

SEE ALSO

DataType(), DataDimension(), defined()