14

---

File Commands and Functions

---

This chapter contains information on the following commands:

close

fscanf

gets

infile

load

newline

outfile

pfile

printf

println

close

close(
p_port
) 
=> t

Description

Drains, closes, and frees a port.

When a file is closed, it frees the FILE* associated with p_port. Do not use this function on piport, stdin, poport, stdout, or stderr.

Arguments

p_port

Name of port to close.

Value Returned

t	The port closed successfully.

Example

p = outfile( "~/test/myFile" ) => port:"~/test/myFile" 

close( p ) 
=> t

Drains, closes, and frees the /test/myFile port.

fscanf

fscanf( 
p_inputPort
t_formatString 
[ s_var1 ... ]  
) 
=> x_items / nil

Description

Reads input from a port according to format specifications and returns the number of items read in.

The results are stored into corresponding variables in the call. The fscanf function can be considered the inverse function of the fprintf output function. The fscanf function returns the number of input items it successfully matched with its format string. It returns nil if it encounters an end of file. The maximum size of any input string being read as a string variable for fscanf is currently limited to 8 K. Also, the function lineread is a faster alternative to fscanf for reading Virtuoso® SKILL objects.

The common input formats accepted by fscanf are summarized below.

Common Input Format Specifications

Format Specification	Types of Argument	Scans for
%d	fixnum	An integer
%f	flonum	A floating-point number
%s	string	A string (delimited by spaces) in the input

Arguments

p_inputPort	Input port to read from.
t_formatString	Format string to match against in the reading.
s_var1…	Name of the variable in which to store results.

Value Returned

x_items	Returns the number of input items it successfully read in. As a side effect, the items read in are assigned to the corresponding variables specified in the call.
nil	Returns nil if an end of file is encountered.

Example

fscanf( p "%d %f" i d )

Scans for an integer and a floating-point number from the input port p and stores the values read in the variables i and d, respectively.

Assume a file testcase with one line:

hello 2 3 world

x = infile("testcase") 
=> port:"testcase"

fscanf( x "%s %d %d %s" a b c d ) 
=> 4

(list a b c d) => ("hello" 2 3 "world")

gets

gets( 
s_variableName 
[ p_inputPort ]
) 
=> t_string / nil

Description

Reads a line from the input port and stores the line as a string in the variable. This is a macro.

The string is also returned as the value of gets. The terminating newline character of the line becomes the last character in the string.

Arguments

s_variableName	Variable in which to store the input string.
p_inputPort	Name of input port. Default value: piport

Value Returned

t_string	Returns the input string when successful.
nil	Returns nil when the end of file is reached. (s_variableName maintains its last value.)

Example

Assume the test1.data file has the following first two lines:

#This is the data for test1

0001 1100 1011 0111

p = infile("test1.data") => port:"test1.data"

gets(s p) => "#This is the data for test1"

gets(s p) => "0001 1100 1011 0111"

s => "0001 1100 1011 0111"

Gets a line from the test1.data file and stores it in the variable s. The s variable contains the last string stored in it by the gets function.

infile

infile( 
S_fileName 
) 
=> p_inport / nil

Description

Opens an input port ready to read a file.

Always remember to close the port when you are done. The file name can be specified with either an absolute path or a relative path. In the latter case, the current SKILL path is used if it is not nil.

Arguments

S_fileName

Name of the file to be read; it can be either a string or a symbol.

Value Returned

p_inport	Returns the port opened for reading the named file.
nil	Returns nil if the file does not exist or cannot be opened for reading.

Example

in = infile( "~/test/input.il" ) => port:"~/test/input.il" 

close( in ) 
=> t

Closes the /test/input.il port.

Opens the input port /test/input.il.

infile("myFile") => nil 

Returns nil if myFile does not exist according to the current setting of the SKILL path or exists but is not readable.

load

load(
t_fileName 
[ t_password ]
) 
=> t

Description

Opens a file and repeatedly calls lineread to read in the file, immediately evaluating each form after it is read in.

This function uses the file extension to determine the language mode (.il for SKILL, .ils for SKILL++, and .ocn for a file containing OCEAN commands) for processing the language expressions contained in the file. For a SKILL++ file, the loaded code is always evaluated in the top-level environment. load closes the file when the end of file is reached. Unless errors are discovered, the file is read in quietly. If load is interrupted by pressing Control-c, the function skips the rest of the file being loaded. SKILL has an autoload feature that allows applications to load functions into SKILL on demand. If a function being run is undefined, SKILL checks to see if the name of the function (a symbol) has a property called autoload attached to it. If the property exists, its value, which must be either a string or an expression that evaluates to a string, is used as the name of a file to be loaded. The file should contain a definition for the function that triggered the autoload. Processing proceeds normally after the function is defined.

Arguments

t_fileName	File to be loaded. Uses the file name extension to determine the language mode to use. Valid values: .ils - Means the file contains SKILL++ code. .ocn - Means the file contains OCEAN commands (with SKILL or SKILL++ commands)
t_password	Password, if t_fileName is an encrypted file.

Value Returned

t	Returns t if the file is successfully loaded.

Example

load( "test.ocn" )

Loads the test.ocn file.

procedure( trLoadSystem() 
    load( "test.il" ) ;;; SKILL code
    load( "test.ils" );;; SKILL++ code
    ) ; procedure

You might have an application partitioned into two files. Assume that test.il contains SKILL code and test.ils contains SKILL/SKILL++ code. This example loads both files.

newline

newline(
[ p_outputPort ]
) 
=> nil

Description

Prints a newline (backslash n) character and then flushes the output port.

Arguments

p_outputPort

Output port. Defaults value: poport

Value Returned

nil	Prints a newline and then returns nil.

Example

print( "Hello" ) newline() print( "World!" )

"Hello" 

"World!" 

=> nil

Prints a newline character after Hello.

outfile

outfile( 
S_fileName
[ t_mode ] 
) 
=> p_outport / nil

Description

Opens an output port ready to write to a file.

Various print commands can write to this file. Commands write first to a character buffer, which writes to the file when the character buffer is full. If the character buffer is not full, the contents are not written to the file until the output port is closed or the drain command is entered. Use the close or drain command to write the contents of the character buffer to the file. The file can be specified with either an absolute path or a relative path. If a relative path is given and the current SKILL path setting is not nil, all directory paths from SKILL path are checked in order, for that file. If found, the system overwrites the first updatable file in the list. If no updatable file is found, it places a new file of that name in the first writable directory.

Arguments

S_fileName	Name of the file to open or create.
t_mode	Mode in which to open the file. If a, the file is opened in append mode; If w, a new file is created for writing (any existing file is overwritten). Default value: w

Value Returned

p_outport	An output port ready to write to the specified file.
nil	returns nil if the named file cannot be opened for writing. An error is signaled if an illegal mode string is supplied.

Example

p = outfile( "/tmp/out.il" "w" ) 
=> port:"/tmp/out.il" 

Opens the /tmp/out.il port.

outfile( "/bin/ls" ) 
=> nil

Returns nil, indicating that the specified port could not be opened.

pfile

pfile(
[ S_fileName | p_port ]
) 
=> p_port / nil

Description

Opens an output port ready to write to a file or returns the name of an existing port indicating that it is available.

This command is similar to the outfile command when a valid S_fileName is specified. When p_port is specified, it returns the file port that is currently being used by p_port. When no argument is specified, it opens the stdout port.

Arguments

S_fileName	Name of the file to open or create.
p_port	Retrieves the name of the file port that is being used.

Value Returned

p_port	The ID of the port that was opened, or stdout.
nil	Returns nil if the named file cannot be opened for writing.

Example

p = pfile( "/tmp/out.il" "w" ) 
=> port:"/tmp/out.il" 

Opens the /tmp/out.il port.

pfile( "/bin/ls" ) 
=> nil

Returns nil, indicating that the specified port could not be opened.

p = pfile() 
=> port:"*stdout*"

Returns stdout as the file port indicating that stdout has been opened.

pfile( p ) 
=> port:"/tmp/out.il"

Returns the file port.

printf

printf( 
t_formatString
[ g_arg1 ... ]
) 
=> t

Description

Writes formatted output to poport, which is the standard output port.

The optional arguments following the format string are printed according to their corresponding format specifications. Refer to the Common Output Format Specifications table for fprintf in the Cadence SKILL Language User Guide.

printf is identical to fprintf except that it does not take the p_port argument and the output is written to poport.

Arguments

t_formatString	Characters to be printed verbatim, intermixed with format specifications prefixed by the “%” sign.
g_arg1…	Arguments following the format string are printed according to their corresponding format specifications.

Value Returned

t	Prints the formatted output and returns t.

Example

x = 197.9687 => 197.9687

printf( "The test measures %10.2f." x )

Prints the following line to poport and returns t.

The test measures 197.97. => t

println

println(
g_value
[ p_outputPort ]
)
=> nil

Description

Prints a SKILL object using the default format for the data type of the value, and then prints a newline character.

A newline character is automatically printed after printing g_value. The println function flushes the output port after printing each newline character.

Arguments

g_value	Any SKILL value.
p_outputPort	Port to be used for output. Default value: poport

Value Returned

nil	Prints the given object and returns nil.

Example

for( i 1 3 println( "hello" ))
"hello" 
"hello" 
"hello" 

=> 
t

Prints hello three times. for always returns t.

Return to top