BoardSurfers: A Guide to File Input/Output Operations in Allegro SKILL Language

9 Jul 2024 • 11 minute read

Efficient file Input/Output (I/O) operations are crucial for seamless workflow management. Allegro SKILL language offers a robust set of utility functions for handling I/O file operations. This post delves into the intricacies of file I/O operations used in Allegro SKILL language and demonstrates advanced file handling capabilities.

Basic SKILL File I/O Functions

The SKILL language provides a comprehensive suite of utility functions tailored for file management. From checking file existence to manipulating directories, SKILL functions equip you with the tools necessary to streamline file operations. These functions facilitate seamless interaction with files and directories in Cadence tools.

The following table explains some of the essential Cadence SKILL file-access functions. These SKILL functions are generic and can be used for writing code in all types of SKILL languages, such as IC SKILL, CM SKILL, and ALLEGRO SKILL.

The following table lists some Cadence SKILL file-access functions:

Function name	Description
infile	Opens an input port to read a file.
outfile	Opens an output port to write a file.
print, println	Prints the value of an expression in the default format.
(\n) character (newline)	Prints a newline.
printlev	Prints a list with a limited number of elements and levels of nesting.
printf	Writes formatted output.
fprintf	Writes formatted output to a port.
(isFile, isFileName)	Checks if a file exists.
(isDir)	Checks if a path exists and if it is the name of a directory.
(isReadable)	Checks if you have the permission to read a file or list a directory.
(isWritable)	Checks for the permission to write a file or update a directory.
(isExecutable)	Checks for the permission to execute a file or search a directory.
(fileLength)	Determines the number of bytes in a file.
(numOpenFiles)	Returns information about open files.
(fileTell, fileSeek)	Works with file offsets.
(createDir)	Creates a new directory.
(deleteDir)	Deletes a directory.
(deleteFile)	Deletes a file.
(makeTempFileName)	Creates a file with a unique name.
(getDirFiles)	Lists the names of all the files and the directories.
(simplifyFilename)	Expands the name of a file to its full path.
(getWorkingDir)	Returns the current working directory.
changeWorkingDir	Changes the current working directory.

Allegro SKILL File Handling Functions

Allegro SKILL functions builds upon the foundation laid by Cadence SKILL and includes additional file I/O functions. These extended capabilities provide more refined control over file handling tasks. Allegro SKILL functions enhance the file I/O toolkit, improving productivity and flexibility within the EDA ecosystem.

The following table explains some noteworthy Allegro SKILL functions:

Function name	Description
axlDMFindFile	Locates and opens a file.
axlDMGetFile	Returns the full path of the file. Displays an error message if the file cannot be opened.
axlDMOpenFile	Opens a file in a conventional manner—adds an extension and optionally looks it up in the directory defined in the search path. To open the file, the function must include an entry in the Allegro database I/O file (fileops.txt).
axlDMOpenLog	Opens a file for writing log messages using the name of the program or application with the .log extension. Returns the port of the file if it succeeds.
axlDMClose	Closes a file currently opened in any Allegro X layout editor. Instead of the infile or outfile functions, use this function to close the files opened using the axlDMOpenFile or axlDMOpenLog functions.
axlDMBrowsePath	Invokes a standard file browser.
axlDMDirectoryBrowse	Opens a directory browser. Unlike file browsers, you can only select a directory.
axlDMFileBrowse	Opens a standard file browser for the users to select a file.
axlDMFileParts	Breaks a file name into its component parts: directory name, file name, file with extension, and extension.
axlOSFileCopy	Copies a source file to a destination with an optional append flag to determine whether the source file is overwritten or appended.
axlOSFileMove	Moves the source file to the given destination.
axlOSSlash	Changes DOS-style backslashes (\) to UNIX/Linux-style forward slashes (/).
axlRecursiveDelete	Recursively removes specified directories and subdirectories. The operation fails if the directory is write-protected.
axlTempDirectory	Returns the temporary directory for the current platform.
axlTempFile	Generates a unique temporary file in the current directory. By default, the temporary files are written to /tmp directory. However, you can modify this path by specifying a local directory path to the TEMPDIR environment variable.
axlTempFileRemove	Deletes the temporary file and removes its name from the system memory.
axlDMFileError	Returns the error from the last call generated by any axlDMxxx function. Subsequent calls reset the error message; so, you should retrieve the error as soon as a call fails.

File Paths

In SKILL language, paths can generally be specified in using forward slashes (Linux style) for readability. It is important to understand the difference between absolute and relative paths when working with file operations.

Absolute Paths

The absolute path begins with a forward slash character (/). When used as the first character of a name, it represents the root directory of the system. Intermediate levels of directories can use the forward slash character again as a separator.

Example: /home/PCB/skillcode

Relative Paths

A path that does not begin with a forward slash is a relative path.

If the path begins with a period and a forward slash (./), the search begins with the current working directory. For example,

// Open a file named "parameters.txt" in the current directory
file = open("./parameters.txt", "r")

If the path begins with two periods and a slash (../), the search begins with the parent of the current working directory.
When a path that does not begin with '~' or './' is passed to a function, the paths in the SKILL path are used as directory names and prepended to the given path.

The setSkillPath and getSkillPath functions access and change this internal SKILL path setup as follows:

The setSkillPath function sets the path to a list of directories.
The getSkillPath function returns a list of directories in the search order.

SKILL_code

The following example shows how to add a directory, C:/work/skill, to the beginning (prepended) of a search path:

setSkillPath(cons("C:/work/skill" getSkillPath()))
getSkillPath()
("C:/work/skill" "." "C:/Users/kirtis/AppData/Roaming/SPB_Data/pcbenv" "C:/Cadence/SPB_23.1/share/local/pcb/skill" "C:/Cadence/SPB_23.1/share/pcb/etc")

SKILL_code

Using Allegro SKILL Functions

The following examples demonstrate how to use Allegro SKILL file functions:

Example 1: Writing Text to a File

The steps to write text to a file are as follows:

Use the outfile function to obtain an output port on a file.
Use an optional output port parameter to the print or println functions and/or use the required port parameter to the fprintf function.
Close the output port with the close function.

The following code writes this data to the myFile.txt file:

myPort = outfile( "myFile.txt" )
for( i 1 3
println( list( "Number:" i) myPort )
)
close( myPort )

It is recommended to specify the full path with the outfile function. Keep in mind that outfile returns nil if you don’t have write access to the file or if it can’t be created in the directory specified in the path.

Watch videos on Writing Data to a Text File Using SKILL and Understanding print functions in SKILL to gain a better understanding.

Example 2: Reading Text from a File

The steps to read a text file are as follows:

Use the infile function to obtain an input port.
Use the gets function to read the file one line at a time, and/or use the fscanf function to convert text fields after receiving the input.
Close the input port with the close function.

The following example prints every line in the abc.txt file:

inPort = infile( "abc.txt" )
when( inPort
while( gets( nextLine inPort )
println( nextLine )
)
close( inPort )
)

Watch this video demonstrating how to read data from a Text File using SKILL.

Example 3: Retrieve a List of Subdirectories Within a Specified Path and Write it to a File

To retrieve a list of subdirectories within a specified path, use getDirFiles and isDir functions using the following code:

(procedure getDirsInPath(inpath)
(let (_dirs _dirList _path _curFullDir)
_path = axlOSSlash(inpath)
_dirs = getDirFiles(_path)
_dirs = remove("." _dirs)
_dirs = remove(".." _dirs)
_dirList = list()
(foreach _curDir _dirs
_curFullDir = (strcat _path "/" _curDir)
(if Isidra(_curFullDir) then
_dirList = cons(_curDir _dirList)
)
)
printf("Number of directories in given path: %d\n" length(_dirList))
printf("Directory list: %L\n" _dirList)
)
)

Example 4: Writing to a File and Displaying it in a Window

Use the axlDMOpenFile function to open a file for writing and axlUIViewFileCreate to open a window to display it.

The following image shows a file created using axlDMOpenFile, displaying the sum of selected cline segments using axlUIViewFileCreate:

segment_sum

The steps to add text to a file in Allegro SKILL language, are as follows:

Use the axlDMOpenFile function to obtain an output port on a file.
Use fprintf, print, or println functions.
Close the output port using the axlDMCloseFile function.

rep_file = axlDMOpenFile("ALLEGRO_REPORT" "sumOfNets" "w")
...
fprintf(rep_file "Net name is %s Length %L Its Start and End Points %L/n" dbid->net->name length dbid->startEnd)
...
fprintf(rep_file "Sum is %L/n" sum)
...
axlDMClose(rep_file)

The file specified in axlDMOpenFile is, by default, created in the current design directory and can be opened in any text editor, such as Notepad++. Calling the function again, renames the existing file with ",1" extension and creates a new file. In this example, running the example code the second time, creates sumOfNets.rpt and sumOfNets.rpt,1 files.

To display the file, it opens a window to display the file. This function takes various parameters, such as the title and the size of the window, to delete a file whether closed or not open.

For detailed information on each function, refer to Allegro SKILL Reference Guide. Also, check out the video on How to write into a file and display it in a window using Allegro SKILL.

Conclusion

Mastering file I/O operations is crucial for maximizing efficiency and productivity in design workflows. Allegro SKILL language provides a robust set of functions for managing file handling tasks with ease. By harnessing the power of these file I/O functions, you can streamline file operations and elevate your design processes to new heights of efficiency. Whether it is navigating directories or managing temporary files, Allegro SKILL language equips designers with functions for efficient file handling capabilities.

Contact Us

For any feedback or topics you want us to include in our blogs, write to us at pcbbloggers@cadence.com.

Subscribe to stay updated about our upcoming blogs.

About BoardSurfers

The BoardSurfers series provides solutions to the various tasks related to the creation and management of PCB design using the Allegro platform products. The name and logo of this series are designed to resonate with the vision of making the design and manufacturing tasks enjoyable, just like surfing the waves. Regular, new blog posts by experts cover every aspect of the PCB design process, such as library management, schematic design, constraint management, stackup design, placement, routing, artwork, verification, and much more.