System_open block

Short summary

NameSystem_open
→POU type→function
Categorymore system blocks, blocks for calling system functions, block with internal error diagnostic
Graphical interface

Available since
  • version 1.13.0 (for logi.CAD 3 ) and version 2.3.901 of logi.RTS – initial variant
    (warning) This block is supported for →Raspberry Pi only.
  • version 1.28.0 (for logi.CAD 3 ) and version 2.3.1301 of logi.RTS – enhancement: with input mode
    (warning) This block is supported for →Raspberry Pi only.
  • version 1.54.0 (for logi.CAD 3 ) and version 3.0.9 of logi.RTS – enhancement: additional output rc
    (warning) This block is supported for the built-in PLC and for Raspberry Pi only.
  • version 1.109.0 (for logi.CAD 3 ) and version 3.19.0 of logi.RTS
    (warning) This block is supported for the built-in PLC, for Raspberry Pi and when using the platform LinuxX86 only.
  • version 2.0.4 (for library System) and version 3.23.0 of logi.RTS

    (warning) This block is supported for the built-in PLC, when using the platform LinuxX86 and the following target systems:

    Raspberry Pi, →MICA→phyBOARD-Regor→phyBOARD-Wega→µMIC.200

Functionality

The block prepares a file, device, or device file to be used by subsequent system calls, such as System_ioctl blockSystem_read block or System_write block.

Required expertise

In order to use this block efficiently, you have to be familiar with the functionality of the underlying system call for the operating system used on the PLC.

Inputs, outputs, return value


Identifier→Data typeDescription
Inputs: pathnameSTRINGstring representing the resource
flagsDINT

access mode and/or creation flags
Valid values for Windows are e.g.: 0 = read only, 1 = write only, 2 = read and write.

Possible values for Windows are listed under: http://www.delorie.com/djgpp/doc/incs/fcntl.h
Possible values for Linux are listed under: http://unix.superglobalmegacorp.com/Net2/newsrc/sys/fcntl.h.html

It is possible to combine values by using the IOR block (see example below).

modeDINT

file system permissions (optional; POSIX style)
But this input is mandatory, if you want to create a new file. 

Possible values for Windows are listed under: https://www.rpi.edu/dept/cis/software/g77-mingw32/include/sys/stat.h
Possible values for Linux are listed under: http://unix.superglobalmegacorp.com/Net2/newsrc/sys/stat.h.html

Outputs: rcDINT

return code:

  • 0 = no error
  • -1 = invalid file descriptor
  • -2 = invalid number of bytes to read/write
  • -3 = failed system call
  • -4 = system service not loaded

errnoDINT

error code returned by the system call

Windows standard values (valid for built-in PLC): see https://msdn.microsoft.com/en-us/library/t3ayayh1.aspx 
Linux standard values (valid for Raspberry Pi: siehe http://www-numi.fnal.gov/offline_software/srt_public_context/WebDocs/Errors/unix_system_errors.html

Return value:DINTreturns the file descriptor on success

Input EN and output ENO are available when →calling the block. See "Execution control: EN, ENO" for information on input EN and output ENO.

Internal error diagnostic for block

The block checks the following error cases:

  • The system service has not been loaded.
  • The return value of the block is a negative value.
  • The return code of the function call equates to an error (output rc ≠ value 0).

In such an error case, the output ENO of the block is set to value FALSE (or an equivalent).

Example for usage within ST-editor

Function block with selected calls of system functions
FUNCTION_BLOCK ExampleSystemOpen
    VAR
        data : ARRAY[0..63] OF BYTE;
        fd : DINT := -1;
        flagsWriteAppend : DINT := -1;
        flagsCreateTruncWrite : DINT := -1;
        mode : DINT := -1;
        path : STRING[64];
        didOpen : BOOL;
        writeOk : BOOL;
    END_VAR
    
    VAR CONSTANT
        /* Append new information to the end of the file. */
        Windows_O_APPEND : DINT := 8;
        /* If the file does not exist, create it. If the O_CREAT option is used, then you must include the third parameter (). */
        Windows_O_CREAT  : DINT := 256;
        /* Combined with the O_CREAT option, it ensures that the caller must create the file. If the file already exists, the call will fail. */
        Windows_O_EXCL   : DINT := 1024;
        /* Open the file so that it is read only. */
        Windows_O_RDONLY : DINT := 0;
        /* Open the file so that it can be read from and written to. */
        Windows_O_RDWR   : DINT := 2;
        /* Initially clear all data from the file. */
        Windows_O_TRUNC  : DINT := 512;
        /* Open the file so that it is write only. */
        Windows_O_WRONLY : DINT := 1;
        
        /* Only reading permitted. */
        Windows_S_IREAD : DINT := 256;
        /* Writing permitted. (In effect, permits reading and writing.) */
        Windows_S_IWRITE : DINT := 128;
        
        /* Append new information to the end of the file. */
        Linux_O_APPEND : DINT := 8;
        /* If the file does not exist, create it. If the O_CREAT option is used, then you must include the third parameter (mode). */
        Linux_O_CREAT  : DINT := 512;
        /* Combined with the O_CREAT option, it ensures that the caller must create the file. If the file already exists, the call will fail. */
        Linux_O_EXCL   : DINT := 2048;
        /* Open the file so that it is read only. */
        Linux_O_RDONLY : DINT := 0;
        /* Open the file so that it can be read from and written to. */
        Linux_O_RDWR   : DINT := 2;
        /* Initially clear all data from the file. */
        Linux_O_TRUNC  : DINT := 1024;
        /* Open the file so that it is write only. */
        Linux_O_WRONLY : DINT := 1;
    END_VAR
    
    IF isTargetWinX86() THEN
        path := 'c:\tmp\log.dat';
        /* write access, append to file content */
        flagsWriteAppend := IOR(Windows_O_WRONLY, Windows_O_APPEND);
        /* write access, create file and truncate file to length 0 */
        flagsCreateTruncWrite := IOR(Windows_O_WRONLY, Windows_O_CREAT, Windows_O_TRUNC);
        /* read and write access for the user */
        mode := IOR(Windows_S_IREAD, Windows_S_IWRITE);
    END_IF;
    
    IF isTargetLinuxX86() THEN
        path := '/tmp/log.dat';
        /* write access, append to file content */
        flagsWriteAppend := IOR(Linux_O_WRONLY, Linux_O_APPEND);
        /* write access, create file and truncate file to length 0 */
        flagsCreateTruncWrite := IOR(Linux_O_WRONLY, Linux_O_CREAT, Linux_O_TRUNC);
        /* read and write access for the user, read access for the group: rw-r----- */
        mode := 2#110100000; 
    END_IF;
    
    fd := System_open(pathname := path, flags := flagsWriteAppend, ENO => didOpen);
    
    /* file does not exist yet */
    IF NOT(didOpen) THEN
        fd := System_open(pathname := path, flags := flagsCreateTruncWrite, mode := mode, ENO => didOpen);
        Assert(fd >= 0);
    END_IF;
    IF didOpen THEN
        /* modify values of data array */
        data[0] := 16#48;
        data[1] := 16#69;
        System_write(fd := fd, count := 2, data := data, ENO => writeOk);
        Assert(writeOk);
        
        System_close(fd := fd);
        System_delete(pathname := path);
    END_IF;
END_FUNCTION_BLOCK

When creating your application within the ST-editor, enter a call of a block by typing the text as requested by the syntax or use Content Assist.