Functions
SAT_OBJECT	sat3_home ()
	Get HOME directory.
SAT_OBJECT	sat3_hiddendir ()
	Get the Hidden directory.
SAT_OBJECT	sat3_getcwd ()
	Get current work directory.
BOOL	sat3_setcwd (SAT_OBJECT dir)
	Set the current work directory.
SAT_OBJECT	sat3_findfirst (SAT_OBJECT dir)
	Get first object in a directory.
SAT_OBJECT	sat3_findnext (SAT_OBJECT dir, SAT_OBJECT diritem)
	Get next object in a directory.
BOOL	sat3_getvarname (SAT_OBJECT obj, char *namebuffer, int max_chars)
	Get next name of an object in a directory.
int	sat3_getvarnamelen (SAT_OBJECT obj)
	Get next length of the name of an object in a directory.
SAT_OBJECT	sat3_updir (SAT_OBJECT dir)
	Get parent directory.
SAT_OBJECT	sat3_rclindir (SAT_OBJECT dir, char *name)
	Find an object within a dir given its name.
SAT_OBJECT	sat3_rclhere (char *name)
	Find an object in the current work directory.
SAT_OBJECT	sat3_rcl (char *name)
	Find an object in the current work directory or its parent directories.
BOOL	sat3_getpath (SAT_OBJECT obj, char *pathbuffer, int maxchars)
	Get the full path and name of an object.
BOOL	sat3_purgeobj (SAT_OBJECT varobject)
	Delete an object in a directory.
BOOL	sat3_purge (char *varpath)
	Delete an object in the current work directory.
BOOL	sat3_purgeindir (SAT_OBJECT dir, char *varname)
	Delete an object in the given directory.
BOOL	sat3_stoindir (SAT_OBJECT dir, SAT_OBJECT obj, char *name)
	Store an object in the given directory.
BOOL	sat3_sto (SAT_OBJECT obj, char *varname)
	Store an object in the current work directory.
BOOL	sat3_crdir (char *name)
	Create a directory in the current work directory.
BOOL	sat3_pgdir (char *name)
	Purge an entrire directory tree.
BOOL	sat3_chdir (char *dir)
	Change the current work directory, given a directory name.

Detailed Description

This group includes all functions used to manage directories.

Function Documentation

BOOL sat3_chdir ( char * dir )

Change the current work directory, given a directory name.

Change the current dir to the given directory name. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the given directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

dir	A directory name.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_setcwd sat3_getttcwd sat3_getpath

BOOL sat3_crdir ( char * name )

Create a directory in the current work directory.

Create an empty directory in the current work directory. If an object with the same name is found, it is replaced without question. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the given directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

name	A directory name.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_pgdir sat3_chdir

SAT_OBJECT sat3_findfirst ( SAT_OBJECT dir )

Get first object in a directory.

Parameters:

dir	A directory object.

Returns:: Returns a SAT_OBJECT with the first object, or 0 if dir is empty or not a dir.

See also:: sat3_findnext

SAT_OBJECT sat3_findnext	(	SAT_OBJECT	dir,
		SAT_OBJECT	diritem
	)

Get next object in a directory.

Obtain the object that follows a given object in a directory.

Parameters:

dir	A directory object.
diritem	An item within the directory

Returns:: Returns a SAT_OBJECT with the next object, or 0 if end-of-dir is reached or not a dir.

See also:: sat3_findfirst

SAT_OBJECT sat3_getcwd ( )

Get current work directory.

Returns:: A SAT_OBJECT pointing to the current directory

BOOL sat3_getpath	(	SAT_OBJECT	obj,
		char *	pathbuffer,
		int	maxchars
	)

Get the full path and name of an object.

Given an object in a directory, extract full path and name information.

Parameters:

obj	An object within a directory.
pathbuffer	A preallocated buffer that will receive the path string.
maxchars	Maximum number of chars that can be stored in the buffer.

Returns:: Returns a true if successful, in such case pathbuffer contains the requested null-terminated path string. On error it returns false. If the path is longer than maxchars the function will fail.

BOOL sat3_getvarname	(	SAT_OBJECT	obj,
		char *	namebuffer,
		int	max_chars
	)

Get next name of an object in a directory.

Given an object, obtain its name if the object is within a directory.

Parameters:

obj	An item within a directory
namebuffer	A preallocated buffer that will receive the name
max_chars	Maximum number of characters to copy to the buffer.

Returns:: True if successful, in such case namebuffer contain the null-terminated name. If max_chars is insufficient to contain the full name, the function will fail. It returns false on error.

See also:: sat3_getvarnamelen

int sat3_getvarnamelen ( SAT_OBJECT obj )

Get next length of the name of an object in a directory.

Given an object, obtain its name length if the object is within a directory.

Parameters:

obj	An item within a directory

Returns:: Integer with the number of characters in the name. Null-named variables are legal and will return 0. On error returns -1.

See also:: sat3_getvarname

SAT_OBJECT sat3_hiddendir ( )

Get the Hidden directory.

Returns:: A SAT_OBJECT pointing to the Hidden directory

SAT_OBJECT sat3_home ( )

Get HOME directory.

Returns:: A SAT_OBJECT pointing to the HOME directory

BOOL sat3_pgdir ( char * name )

Purge an entrire directory tree.

Given a directory name, it deletes the directory, all its contents and subdirectories. This function is an alias for sat3_purge, which causes the same effect when given a directory name.

Parameters:

name	A directory name.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_crdir sat3_chdir

BOOL sat3_purge ( char * varpath )

Delete an object in the current work directory.

Scan the current work directory for the requested name. If found it deletes the object. The function will fail if trying to delete a referenced object, or if the given object contains an object that is referenced from another location (like the stack). The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the current work directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

varpath A variable name, which may contain path information.

Returns:: Returns a true if successful. On error it returns false, which may happen because the given object is not on a directory or because it's being referenced from another location.

See also:: sat3_purgeindir sat3_purgeobj

BOOL sat3_purgeindir	(	SAT_OBJECT	dir,
		char *	varname
	)

Delete an object in the given directory.

Scan the given directory for the requested name. If found it deletes the object. The function will fail if trying to delete a referenced object, or if the given object contains an object that is referenced from another location (like the stack). The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the current work directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

dir	A directory object.
varpath	A variable name, which may contain path information.

Returns:: Returns a true if successful. On error it returns false, which may happen because the given object is not on a directory or because it's being referenced from another location.

See also:: sat3_purgeobj sat3_purge

BOOL sat3_purgeobj ( SAT_OBJECT varobject )

Delete an object in a directory.

Purge (delete) an object in a directory. It can delete non-empty directories in one call. The function will fail if trying to delete a referenced object, or if the given object contains an object that is referenced from another location (like the stack).

Parameters:

varobject An object within a directory.

Returns:: Returns a true if successful. On error it returns false, which may happen because the given object is not on a directory or because it's being referenced from another location.

See also:: sat3_purge sat3_purgeindir

SAT_OBJECT sat3_rcl ( char * name )

Find an object in the current work directory or its parent directories.

Scan the current work directory for the requested name. If found it returns a SAT_OBJECT pointing to the object, if not found it scans the parent directory for the name until the name is found or the HOME directory is reached. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the current work directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

name	A variable name.

Returns:: Returns a SAT_OBJECT that corresponds to the given name, 0 if not found.

See also:: sat3_rclindir sat3_rclhere

SAT_OBJECT sat3_rclhere ( char * name )

Find an object in the current work directory.

Scan the current work directory for the requested name. If found it returns a SAT_OBJECT pointing to the object. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the current work directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

name	A variable name.

Returns:: Returns a SAT_OBJECT that corresponds to the given name, 0 if not found.

See also:: sat3_rclindir sat3_rcl

SAT_OBJECT sat3_rclindir	(	SAT_OBJECT	dir,
		char *	name
	)

Find an object within a dir given its name.

Scan the given directory for the requested name. If found it returns a SAT_OBJECT pointing to the object. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the given directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

dir	A directory object.
name	A variable name.

Returns:: Returns a SAT_OBJECT that corresponds to the given name, 0 if not found.

See also:: sat3_rclhere sat3_rcl

BOOL sat3_setcwd ( SAT_OBJECT dir )

Set the current work directory.

Set the current work directory to the given one.

Parameters:

dir	A directory object.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_getcwd sat3_chdir

BOOL sat3_sto	(	SAT_OBJECT	obj,
		char *	varname
	)

Store an object in the current work directory.

Store the given object using the given name in the current directory. If an object with the same name is found, it is replaced without question. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the given directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

obj	The object to store.
name	A variable name.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_stoindir

BOOL sat3_stoindir	(	SAT_OBJECT	dir,
		SAT_OBJECT	obj,
		char *	name
	)

Store an object in the given directory.

Store the given object using the given name in the specified directory. If an object with the same name is found, it is replaced without question. The name can contain path information in DOS/Unix fashion. Both forward slash / and backslash \ are acceptable directory separators. A starting slash begins the search at HOME, otherwise the given directory is searched. Double dots '..' represent the parent directory. Examples of valid paths are: "myVAR", "/myVAR" (at HOME), "/mydir/myVAR", "../mydir/myVAR", "../../myVAR". Null-named variables and directories are acceptable, so "//myVAR" will search in the Hidden directory, and "/mydir/" will try to find a null-named variable in /mydir.

Parameters:

dir	A directory object.
obj	The object to store.
name	A variable name.

Returns:: Returns true if successful, false otherwise.

See also:: sat3_sto

SAT_OBJECT sat3_updir ( SAT_OBJECT dir )

Get parent directory.

Obtain the parent directory of a directory. It does not alter the current work directory. Use sat3_setcwd for that.

Parameters:

dir	A directory object.

Returns:: Returns a SAT_OBJECT with the parent dir, or 0 if not a dir.

See also:: sat3_setcwd sat3_getcwd

Directory functions

Functions

Detailed Description

Function Documentation