Storage Format

This chapter describes the file-based storage format. This includes explanations of the text encoding of the files, the folder structure, the storage of programming objects and their metadata, as well as the source text in structured text and in graphical languages.

Text encoding and formatting

The same conventions are followed for every file which is written by CODESYS File-Based Storage. This keeps projects portable between operating systems and creates clean differences in version control systems.

Encoding: All text files are written in UTF-8 without the Byte Order Mark (BOM). When an existing XML file is read, the specified encoding is used. An existing Byte Order Mark is tolerated.
End of Line: Files are written with the line feed character (\n). When a file is read, both the line feed and the Windows end of line (\r\n) are accepted.
End of Line in version control systems
Configure the version control system so that line breaks are preserved as end of line in order to avoid unnecessary differences.
Indentation: JSON and XML files are indented with one tab character per nesting level.

Folders

Each folder in the project tree becomes a directory with the same name. A folder optionally has a metadata file named .folder_meta.json. This file stores the object GUID of the folder and its properties:

{
	"objectGuid": "1b3a0c5e-...",
	"properties": {
		"PropertyName": "PropertyValue"
	}
}

In CODESYS 3, each folder has an object GUID. This is written in the .folder_meta.json file so that the folder can still be tracked even after renaming and moving. The properties field is written only if the folder has properties. Otherwise, it is omitted. In CODESYS 4, a folder does not have an object GUID. A folder without saved metadata does not have a .folder_meta.json file.

Programming objects

Each programming object is saved as a separate text file. The filename has the following syntax:

<object name>.<class>.<language>

The class part specifies the object type and the language part specifies the implementation language. Specifically, the language part for structured text is st. An example of a function block in structured text is Timer.fb.st.

Object Type	Class Part	Example
Program	`prg`	`Main.prg.st`
Function block	`fb`	`Timer.fb.st`
Function	`fn`	`Add.fn.st`
Method	`meth`	`Start.meth.st`
Action	`act`	`Reset.act.st`
Transition	`trans`	`Step1.trans.st`
Property of a POU	`prop.st`	`Enabled.prop.st`
Interface	`itf`	`IMotor.itf`
Interface method	`meth`	`Run.meth`
Interface property	`prop`	`Speed.prop`
Structure (DUT)	`struct`	`Point.struct`
Enumeration (DUT)	`enum`	`Color.enum`
Alias (DUT)	`alias`	`Distance.alias`
Union (DUT)	`union`	`Value.union`
Global variable list	`gvl`	`Globals.gvl`

An object with subordinate objects (for example, a function block with methods) is stored as a directory whose name ends with a caret (^). The object itself is the file in this directory. The subordinate objects are located next to them:

Timer.fb.st^/
    Timer.fb.st    (der Funktionsbaustein selbst)
    Start.meth.st    (eine Methode)
    Stop.meth.st    (eine Methode)

Object metadata

If an object contains metadata which cannot be reconstructed in another way, then the file is started with a metadata comment. Examples include a stable object GUID or object properties. The comment is marked with (* METADATA … *). The metadata is stored as JSON.

(* METADATA
{
	"v3Meta": {
		"objectGuid": "e75fc257-..."
	}
}
*)

If an object does not contain metadata, then no metadata comment is written and the file starts directly with the object header.

The project information (title, version, author, company, description, and other settings) is stored in the ProjectInfo.json file in the project root directory.

Source text of objects in structured text

Structured text is stored as plain text without markers. The declaration part is always written first, directly followed by the implementation part.

Example 1. Example

The following example shows the structured text PLC_PRG program in the PLC_PRG.prg.st file.

PROGRAM PLC_PRG
VAR
    nCounter : INT;
END_VAR
nCounter := nCounter + 1;
END_PROGRAM

Source text of graphical languages

Languages other than structured text – the graphical languages, such as Ladder Diagram (LD), Function Block Diagram (FBD), Continuous Function Chart (CFC), and Sequential Function Chart (SFC) – cannot be written as structured text. For these languages, the declaration is still stored as plain text. However, the implementation section is enclosed by two marker lines which cite the respective language.

FUNCTION_BLOCK TSSend
VAR_INPUT
    xExecute : BOOL;
END_VAR
__BEGIN_IMPLEMENTATION('CFC')
{
    ... die Implementierung im eigenen Format der Sprache ...
}
__END_IMPLEMENTATION
END_FUNCTION_BLOCK

The implementation begins with the marker __BEGIN_IMPLEMENTATION('<language>') which cites the language (for example, LD for Ladder Diagram, FBD for Function Block Diagram, CFC for Continuous Function Chart, or SFC for Sequential Function Chart). It will be closed with the marker __END_IMPLEMENTATION. Everything between the markers is stored in the text format of the respective language. For the integrated graphical languages, this format is used as JSON, indented with one tab character per nesting level.

The markers make sure that the declaration is reliably separated from the contents of the implementation part, regardless of its contents. No markers are needed or used for structured text.

Objects without a native format

Not every object type has its own text representation. Objects such as device configurations and task configurations are saved in a swap file with the extension xml.v3, which encloses the original CODESYS serialization. These files remain text files and will continue to create line-by-line differences in version control systems. These kinds of objects can later be migrated to a native format as soon as one is available.

For more information, see the following: Migrate Objects

If the contents of an object cannot be interpreted at all, then the object remains unchanged so that no information is lost.

In this section: