IsDirectory

# IsDirectory

Name:

IsDirectory

Syntax:

    INTEGER IsDirectory([FILE_INFO] info)

Description:

This routine returns whether the specified file is a directory, equivalent to checking info.;Attributes.

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description).

Return Value:

Returns 1 if  file is a directory and 0 otherwise.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

 StartFileOperations();

    Found = FindFirst("\*.dat", FileInfo );

    WHILE (Found = 0)

    {

      if (IsDirectory(FileInfo))

          PRINT( "%s is a directory\n", FileInfo.Name );

      Found = FindNext(FileInfo);

    }

    IF ( FindClose() \< 0 )

      PRINT ( "Error in closing find operation\n" );

 EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.03.18 and later

  [FILE_INFO]: File_INFO_Structure.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ISDIRECTORY
IsDirectory

EndFileOperations FILE_INFO File FindClose FindFirst FindNext Functions IF INTEGER IsDirectory Overview PRINT SIGNED_INTEGER StartFileOperations WHILE

FILE_INFO
FindFirst
File Functions Overview


IsHidden

# IsHidden

Name:

IsHidden

Syntax:

    INTEGER IsHidden(FILE_INFO info)

Description:

This routine returns whether the specified file is hidden. Equivalent to checking attributes in [FILE_INFO].

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description).

Return Value:

Returns 1 if file is hidden and 0 if otherwise.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

 StartFileOperations();

    Found = FindFirst("\*.dat", FileInfo );

    WHILE (Found = 0)

    {

      if (IsHidden(FileInfo))

          PRINT( "%s is hidden\n", FileInfo.Name );

      Found = FindNext(FileInfo);

    }

    IF ( FindClose() \< 0 )

      PRINT ( "Error in closing find operation\n" );

 EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FILE_INFO]: File_INFO_Structure.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ISHIDDEN
IsHidden

EndFileOperations FILE_INFO File FindClose FindFirst FindNext Functions IF INTEGER IsHidden Overview PRINT SIGNED_INTEGER StartFileOperations WHILE


IsReadOnly

# IsReadOnly

Name:

IsReadOnly

Syntax:

    INTEGER IsReadOnly(FILE_INFO info)

Description:

This routine returns whether the specified file is marked as read-only. Equivalent to checking attributes in [FILE_INFO].

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description).

Return Value:

Returns 1 if file is read-only and 0 if otherwise.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

 StartFileOperations();

    Found = FindFirst("\*.dat", FileInfo );

    WHILE (Found = 0)

    {

      if (IsReadOnly(FileInfo))

          PRINT( "%s is read-only\n", FileInfo.Name );

      Found = FindNext(FileInfo);

    }

    IF ( FindClose() \< 0 )

      PRINT ( "Error in closing find operation\n" );

 EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FILE_INFO]: File_INFO_Structure.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ISREADONLY
IsReadOnly

EndFileOperations FILE_INFO File FindClose FindFirst FindNext Functions IF INTEGER IsReadOnly Overview PRINT SIGNED_INTEGER StartFileOperations WHILE


IsSystem

# IsSystem

Name:

IsSystem

Syntax:

    INTEGER IsSystem(FILE_INFO info)

Description:

This routine returns whether the specified file is a system file. Equivalent to checking attributes in [FILE_INFO].

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description).

Return Value:

Returns 1 if file is a system file and 0 if otherwise.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

 StartFileOperations();

    Found = FindFirst("\*.dat", FileInfo );

    WHILE (Found = 0)

    {

      if (IsSystem(FileInfo))

          PRINT( "%s is a system file\n", FileInfo.Name );

      Found = FindNext(FileInfo);

    }

    IF ( FindClose() \< 0 )

      PRINT ( "Error in closing find operation\n" );

 EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FILE_INFO]: File_INFO_Structure.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ISSYSTEM
IsSystem

EndFileOperations FILE_INFO File FindClose FindFirst FindNext Functions IF INTEGER IsSystem Overview PRINT SIGNED_INTEGER StartFileOperations WHILE


IsVolume

# IsVolume

Name:

IsVolume

Syntax:

    INTEGER IsVolume(FILE_INFO info)

Description:

This routine returns whether the specified file is a volume label. Equivalent to checking attributes in [FILE_INFO].

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description).

Return Value:

Returns 1 if file is a volume label and 0 if otherwise.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

 StartFileOperations();

    Found = FindFirst("\*.dat", FileInfo );

    WHILE (Found = 0)

    {

      if (IsVolume(FileInfo))

          PRINT( "volume label = %s\n", FileInfo.Name );

      Found = FindNext(FileInfo);

    }

    IF ( FindClose() \< 0 )

      PRINT ( "Error in closing find operation\n" );

 EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.03.18 and later

  [FILE_INFO]: File_INFO_Structure.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ISVOLUME
IsVolume

EndFileOperations FILE_INFO File FindClose FindFirst FindNext Functions IF INTEGER IsVolume Overview PRINT SIGNED_INTEGER StartFileOperations WHILE


IsNull

# IsNull

**Name:**

IsNull

**Syntax:**

     INTEGER IsNull( \<class_object\> )

**Description:**

IsNull can be used to determine whether or not a class or class member variable is valid.

**ReturnValue:**

IsNull will return 1 if the class or class member variable has not been properly initialized, 0 otherwise.

**Example:**

CMutex myMutex;

FUNCTIONInit()

{

     INTEGER retVal;

     if ( \!IsNull(myMutex) )

     {

          myMutex.WaitForMutex();

     }

     else

     {

print(" myMutex is initialized!\r\n");

     }

}

**Version:**

X Generation: N/A

2-Series: N/A

3-Series:  SIMPL v4.02.02+

Language Constructs & Functions
File Functions
IsNull

FUNCTIONInit INTEGER IsNull WaitForMutex


MakeDirectory

# MakeDirectory

Name:

MakeDirectory

Syntax:

    SIGNED_INTEGER MakeDirectory(STRING DirName)

Description:

Creates a directory with the specified name. The path can be [relative] or absolute.

NOTE: You cannot use MakeDirectory to create directories in the NVRAM or internal flash. You can only make directories in compact flash.

Parameters:

DIRNAME – string containing the name of the desired directory.

Return Value:

Returns 0 if successful. Returns 0 or a [File Function Error Code] if unsuccessful.

Example:

(see [File Functions Overview])

   IF( MakeDirectory("NewDirect") \< 0)

       PRINT("Error occurred creating directory\n");

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [relative]: ../../General_Information/Relative_Path_Names_for_Files.md
  [File Function Error Code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
MakeDirectory

Code Error File Function Functions IF MakeDirectory Overview PRINT SIGNED_INTEGER STRING relative

relative
File Function Error Code
File Functions Overview


MakeDirectoryShared

# MakeDirectoryShared

Name:

MakeDirectoryShared

Syntax:

    SIGNED_INTEGER MakeDirectoryShared(STRING DirName)

Description:

Creates a shared directory with the specified name. The path can be [relative] or absolute.

NOTE: You cannot use MakeDirectoryShared to create directories in the NVRAM or internal flash. You can only make directories in compact flash.

Parameters:

DIRNAME – string containing the name of the desired directory.

Return Value:

Returns 0 if successful. Returns 0 or a [File Function Error Code] if unsuccessful.

Example:

(see [File Functions Overview])

   IF( MakeDirectoryShared("NewDirect") \< 0)

       PRINT("Error occurred creating directory\n");

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [relative]: ../../General_Information/Relative_Path_Names_for_Files.md
  [File Function Error Code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
MakeDirectoryShared

Code Error File Function Functions IF MakeDirectoryShared Overview PRINT SIGNED_INTEGER STRING relative


ReadInteger

# ReadInteger

Name:

ReadInteger

Syntax:

    SIGNED_INTEGER ReadInteger ( INTEGER file_handle, INTEGER i )

Description:

Reads an integer from a file starting at the current file position. Two bytes are read, most significant byte first. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead],  [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray][ReadIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

I is the integer whose value is read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an error code.\
If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

INTEGER i;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadInteger(nFileHandle, i);

      if (iErrorCode \> 0)

        PRINT ( "Read integer from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL v2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadInteger

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadSignedLongIntegerArray ReadString ReadStructure Reading SIGNED_INTEGER StartFileOperations

Reading and Writing Data to a File
FileRead
ReadString
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadSignedLongIntegerArray


ReadIntegerArray

# ReadIntegerArray

Name:

ReadIntegerArray

Syntax:

  SIGNED_INTEGER ReadIntegerArray( INTEGER file_handle,

INTEGER iArray[m][n] )

Description:

Reads the array from a file starting at the current file position. Two bytes are read, most significant first containing the row dimension of the array, then two more bytes are read, containing the column dimension of the array. Then each integer is read as a two byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are read, because there is a row 0 and a column 0.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

IARRAY is the array whose values are read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code]. An error occurs if the array is not large enough to hold the data.

If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

INTEGER iArray[10];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadIntegerArray(nFileHandle, iArray);

      if (iErrorCode \> 0)

        PRINT ( "Read array from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadIntegerArray

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadLongIntegerArray ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStructure Reading SIGNED_INTEGER StartFileOperations

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadSignedIntegerArray
ReadLongIntegerArray


ReadLongInteger

# ReadLongInteger

Name:

ReadLongInteger

Syntax:

  SIGNED_INTEGER ReadLongInteger ( INTEGER file_handle,

LONG_INTEGER li )

Description:

Reads a long integer from a file starting at the current file position. Four bytes are read, most significant byte first and least significant byte last.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger],  [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

LI is the long integer whose value is read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code].

If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

LONG_INTEGER li;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadLongInteger(nFileHandle, li);

      if (iErrorCode \> 0)

        PRINT ( "Read long integer from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadLongInteger

Data EndFileOperations File FileOpen FileRead IF INTEGER LONG_INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadLongIntegerArray ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStructure Reading SIGNED_INTEGER

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadSignedInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadLongIntegerArray


ReadLongIntegerArray

# ReadLongIntegerArray

Name:

ReadLongIntegerArray

Syntax:

    SIGNED_INTEGER ReadLongIntegerArray ( INTEGER file_handle,

LONG_INTEGER ilArray[m][n] )

Description:

Reads the array from a file starting at the current file position. Two bytes are read, most significant first containing the row dimension of the array, then two more bytes are read, containing the column dimension of the array. Then each long  integer is read as a four byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are read, because there is a row 0 and a column 0. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.\
  An error occurs if the array is not large enough to hold the data.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

ilArray is the array whose values are read. If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

LONG_INTEGER ilArray[10];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadLongIntegerArray(nFileHandle, ilArray);

      if (iErrorCode \> 0)

        PRINT ( "Read array from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadLongIntegerArray

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray


ReadSignedInteger

# ReadSignedInteger

Name:

ReadSignedInteger

Syntax:

   SIGNED_INTEGER ReadSignedInteger ( INTEGER file_handle,

SIGNED_INTEGER si )

Description:

Reads a signed integer from a file starting at the current file position. Two bytes are read, most significant first. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray][ReadSignedIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SI is the signed integer whose value is read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code].

If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_INTEGER si;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadSignedInteger(nFileHandle, si);

      if (iErrorCode \> 0)

        PRINT ( "Read signed integer from file correctly\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadSignedInteger

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadLongIntegerArray


ReadSignedIntegerArray

# ReadSignedIntegerArray

Name:

ReadSignedIntegerArray

Syntax:

    SIGNED_INTEGER ReadSignedIntegerArray ( INTEGER file_handle,

SIGNED_INTEGER isArray[m][n] )

Description:

Reads the array from a file starting at the current file position. Two bytes are read, most significant first containing the row dimension of the array, then two more bytes are read, containing the column dimension of the array. Then each signed integer is read as a two byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are read, because there is a row 0 and a column 0. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

ISARRAY is the array whose values are read. If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code]. An error occurs if the array is not large enough to hold the data.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_INTEGER isArray[10][5];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadSignedIntegerArray(nFileHandle, isArray);

      if (iErrorCode \> 0)

        PRINT ( "Read array from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadSignedIntegerArray

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadLongIntegerArray


ReadSignedLongInteger

# ReadSignedLongInteger

Name:

ReadSignedLongInteger

Syntax:

 SIGNED_INTEGER ReadSignedLongInteger ( INTEGER file_handle,

SIGNED_LONG_INTEGER sli )

Description:

Reads data from a file starting at the current file position. Each element of the structure is read, without any padding bytes, that might actually be there in memory. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SLI is the signed long integer whose value is read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code].

If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_LONG_INTEGER sli;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadSignedLongInteger(nFileHandle, sli);

      if (iErrorCode \> 0)

        PRINT ( "Read from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadSignedLongInteger

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadLongIntegerArray ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStructure Reading SIGNED_INTEGER SIGNED_LONG_INTEGER

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadLongIntegerArray


ReadSignedLongIntegerArray

# ReadSignedLongIntegerArray

Name:

ReadSignedLongIntegerArray

Syntax:

    SIGNED_INTEGER ReadSignedLongIntegerArray ( INTEGER file_handle,

SIGNED_LONG_INTEGER sliArray[m][n] )

Description:

Reads the array from a file starting at the current file position. Two bytes are read, most significant first containing the row dimension of the array, then two more bytes are read, containing the column dimension of the array. Then each signed long  integer is read as a four byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are read, because there is a row 0 and a column 0.. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file read functions.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SLIARRAY is the array whose values are read.

Return Value:

Number of bytes read from file.  If the return value is negative, it is an [error code].

If no Return Value is specified within an Integer_Function, then a 0 will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_LONG_INTEGER sliArray[10][5];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadSignedLongIntegerArray(nFileHandle, sliArray);

      if (iErrorCode \> 0)

        PRINT ( "Read array from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadSignedLongIntegerArray

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadSignedLongIntegerArray ReadString ReadStructure Reading SIGNED_INTEGER SIGNED_LONG_INTEGER


ReadString

# ReadString

Name:

ReadString

Syntax:

    SIGNED_INTEGER ReadString ( INTEGER file_handle, STRING s )

Description:

Reads a string from a file starting at the current file position. Internally, the string is stored as a 2-byte length, most significant byte first, then the actual string bytes.  In the case of a string variable, the total number of bytes written is calculated from the size of the string, not the string allocation size. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions: [FileRead], [ReadInteger], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

S is the string whose value is read.

Return Value:

Number of bytes read from file into the string.  If the return value is negative, it is an [error code]. An error occurs if the string is not large enough to hold the data.

If no Return Value is specified within an String_Function, then an empty string will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

STRING s[100];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadString( nFileHandle, s);

      if (iErrorCode \> 0)

        PRINT ( "Read string from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadString

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadLongIntegerArray ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStructure Reading SIGNED_INTEGER STRING

Reading and Writing Data to a File
FileRead
ReadInteger
ReadStructure
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadLongIntegerArray


ReadStringArray

# ReadStringArray

Name:

ReadStringArray

Syntax:

    SIGNED_INTEGER ReadStringArray ( INTEGER file_handle, STRING s[] )

Description:

Reads a string from a file starting at the current file position. Internally, the string is stored with the first 2 bytes indicating the total number of string written, then each string follows as a 2-byte length, most significant byte first, then the actual string bytes. In the case of a string variable, the total number of bytes is calculated from the size of the string, not the string allocation size. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions: [FileRead], [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

S is the string whose value is read.

Return Value:

Number of bytes read from file into the string.  If the return value is negative, it is an [error code]. An error occurs if the array is not large enough to hold the data.

If no Return Value is specified within an String_Function, then an empty string will be returned by default.

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

STRING s[100][100];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_RDONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = ReadStringArray( nFileHandle, s);

      if (iErrorCode \> 0)

        PRINT ( "Read string from file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadStructure]: Read_Structure.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
ReadStringArray

Data EndFileOperations File FileOpen FileRead IF INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStringArray ReadStructure Reading SIGNED_INTEGER STRING


ReadStructure

# ReadStructure

Name:

ReadStructure

Syntax:

   ReadStructure ( INTEGER nFileHandle, STRUCTURE struct [, INTEGER nTotalBytesRead] )

Description:

Reads data from a file starting at the current file position. Each element of the structure is read, without any padding bytes, that might actually be there in memory. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileRead], [ReadInteger], [ReadString], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.\
There is no error if the structure does not match the data.

Parameters:

nFileHandle - File handle of the previously opened file (from [FileOpen]).

struct - Structure variable that will receive data read from file

nTotalBytesRead - optional argument.  INTEGER variable that will contain the

total number of bytes read from the file into the structure.

Return Value:

NONE

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, nTotalBytesRead;

STRUCTURE PhoneBookEntry

{

   STRING Name[50];

   STRING Address[100];

   STRING PhoneNumber[20];

};

PhoneBookEntry OneEntry;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile.txt", _O_RDONLY );

if (nFileHandle \>= 0)

{

   ReadStructure( nFileHandle, OneEntry, nTotalBytesRead );

   if( nTotalBytesRead \< 0 )

      PRINT ( "Error reading structure.  Error code = %d\n", nTotalBytesRead );

   else

      PRINT ( "Read structure from file correctly.  Total bytes read = %d\n", nTotalBytesRead );

}

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileRead]: FileRead.md
  [ReadInteger]: ReadInteger.md
  [ReadString]: ReadString.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [ReadLongInteger]: ReadLongInteger.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [ReadSignedIntegerArray]: ReadSignedIntegerArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
Read Structure
ReadStructure

Data EndFileOperations File FileOpen FileRead INTEGER PRINT ReadInteger ReadIntegerArray ReadLongInteger ReadLongIntegerArray ReadSignedInteger ReadSignedIntegerArray ReadSignedLongInteger ReadString ReadStructure Reading SIGNED_INTEGER STRING STRUCTURE

Reading and Writing Data to a File
FileRead
ReadInteger
ReadString
ReadSignedInteger
ReadLongInteger
ReadSignedLongInteger
ReadIntegerArray
ReadSignedIntegerArray
ReadLongIntegerArray


Reading and Writing Data to a File

# Reading and Writing Data to a File

Reading and writing data to a file that is moved from one kind of a system to another has special programming considerations because it will likely be written on one kind of system, e.g. a PC and read on another, e.g. a Crestron control system, or vice versa.  Most programmers are used to writing programs that are both written by a PC and read by a PC.

The best way to write to a file that must be transferred between systems is to write pure ASCII text and use the [FileRead]/[FileWrite] routines. If you must write binary data as binary, e.g. structures, integers, strings, arrays, please read and consider the following.

Different kinds of systems store their internal data structures with various padding bytes and lengths, that are not always apparent. For example, a structure declared like this:

STRUCTURE

{

STRING s[5];

INTEGER I;

}

may contain a padding byte between the string and the integer, so the integer can begin on a word boundary. But this padding is  system and compiler dependent, as another system or compiler may handle this data perfectly well without a padding byte.  Also, some systems store integers with their most significant byte first ( the industry term is “big-endian”) or with their least significant bytes first (“little-endian”).

Because compact flash is meant to be transferred among different systems, Crestron has given the programmer two different ways to store data. It can be stored with padding bytes by writing the integers, strings, structures, etc directly (see [WriteInteger], [WriteString], [WriteStructure], [WriteIntegerArray], etc) or it can be stored directly as a string of bytes where the programmer controls exactly what is written (see [FileWrite]). There are corresponding functions to read each of these. Data written by one method should be read with the corresponding function. If you must write binary files, Crestron recommends the first way, for system independence. Details are listed in each function.

  [FileRead]: FileRead.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteIntegerArray]: WriteIntegerArray.md

Language Constructs & Functions
File Functions
Reading and Writing Data to a File

Data File FileRead FileWrite INTEGER Reading STRING STRUCTURE WriteInteger WriteIntegerArray WriteString WriteStructure Writing and

FileRead FileWrite WriteInteger WriteString WriteStructure WriteIntegerArray


RemoveDirectoryShared

# RemoveDirectoryShared

Name:

RemoveDirectoryShared

Syntax:

    SIGNED_INTEGER RemoveDirectoryShared(STRING DirName)

Description:

Removes the shared directory with the specified name. The path name can be [relative] or absolute. Must be empty. Requires [StartFileOperations].

Parameters:

DIRNAME – string containing the name of the desired directory.

Return Value:

Returns 0 if successful and –1 if an error occurred.

Example:

(see [File Functions Overview])

   IF( RemoveDirectoryShared("\\CF0\\NewDirect") \< 0)

       PRINT("Error occurred deleting directory\n");

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [relative]: ../../General_Information/Relative_Path_Names_for_Files.md
  [StartFileOperations]: StartFileOperations.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
RemoveDirectoryShared

File Functions IF Overview PRINT RemoveDirectoryShared SIGNED_INTEGER STRING StartFileOperations relative

relative
StartFileOperations
File Functions Overview


RemoveDirectory

# RemoveDirectory

Name:

RemoveDirectory

Syntax:

    SIGNED_INTEGER RemoveDirectory(STRING DirName)

Description:

Removes the directory with the specified name. The path name can be [relative] or absolute. Must be empty. Requires [StartFileOperations].

Parameters:

DIRNAME – string containing the name of the desired directory.

Return Value:

Returns 0 if successful and –1 if an error occurred.

Example:

(see [File Functions Overview])

   IF( RemoveDirectory("\\CF0\\NewDirect") \< 0)

       PRINT("Error occurred deleting directory\n");

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [relative]: ../../General_Information/Relative_Path_Names_for_Files.md
  [StartFileOperations]: StartFileOperations.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
Remove Directory
RemoveDirectory

File Functions IF Overview PRINT RemoveDirectory SIGNED_INTEGER STRING StartFileOperations relative


SetCurrentDirectory

# SetCurrentDirectory

Name:

SetCurrentDirectory

Syntax:

    SIGNED_INTEGER SetCurrentDirectory(STRING DirName)

Description:

Changes the working directory to the specified name. Refer to [Relative Path Names].

Parameters:

DIRNAME – string containing the name of the desired directory.

Return Value:

Returns 0 if successful and –1 if an error occurred.

Example:

(see [File Functions Overview])

   IF( SetCurrentDirectory("\\CF0\\NewDirect") \< 0)

       PRINT("Error occurred creating directory\n");

   PRINT("Directory is now: %s\n", GetCurrentDirectory());

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Relative Path Names]: ../../General_Information/Relative_Path_Names_for_Files.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
SetCurrentDirectory

File Functions GetCurrentDirectory IF Names Overview PRINT Path Relative SIGNED_INTEGER STRING SetCurrentDirectory

Relative Path Names
File Functions Overview


StartFileOperations

# StartFileOperations

Name:

StartFileOperations

Syntax:

    SIGNED_INTEGER StartFileOperations()

Description:

Signifies to the operating system that the current thread is starting its file operations.

Required prior to any operation accessing a file, including all functions in [FileFunctions].

[EndFileOperations] is required after finishing all file operations and prior to terminating the thread of execution (e.g., one of the PUSH commands).

Parameters:

None.

Return Value:

Returns 0 if successful and –1 if an error occurred.

Example:

(see [File Functions Overview][FileFunctions], specifically refer to the note about StartFileOperations)

   IF ( StartFileOperations() \< 0 )

      PRINT ( "Error in starting file ops\n" );

// various file operations

    IF ( EndFileOperations() \< 0 )

      PRINT ( "Error Occurred in ending file ops\n" );

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileFunctions]: File_Functions_Overview.md
  [EndFileOperations]: EndOfFileOperations.md

Language Constructs & Functions
File Functions
StartFileOperations

EndFileOperations FileFunctions IF PRINT PUSH SIGNED_INTEGER StartFileOperations


WaitForNewDisk

# WaitForNewDisk

Name:

WaitForNewDisk

Syntax:

    SIGNED_INTEGER WaitForNewDisk()

Description:

Waits for a compact flash card to be inserted into the control system.

See also [CheckForDisk()].

Parameters:

None.

Return Value:

Returns 0 when a new compact flash card is installed into the control system, \<0 if an error occurs.

Example:

(see [File Functions Overview])

    while(1)

        {

             if ( WaitForNewDisk() \< 0 )

                        break;

             // perform operations on the new disk. Read a file, etc.

        }

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [CheckForDisk()]: CheckForDisk.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WaitForNewDisk

CheckForDisk File Functions Overview SIGNED_INTEGER WaitForNewDisk


WriteInteger

# WriteInteger

Name:

WriteInteger

Syntax:

    SIGNED_INTEGER WriteInteger ( INTEGER file_handle, INTEGER i )

Description:

Writes an integer to a file starting at the current file position. Two bytes are written, most significant byte first. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadInteger] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

I is the integer whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

INTEGER i;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteInteger(nFileHandle, i);

      if (iErrorCode \> 0)

        PRINT ( "Written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadInteger]: ReadInteger.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteInteger

Data EndFileOperations File FileOpen FileWrite IF INTEGER PRINT Reading SIGNED_INTEGER StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteLongIntegerArray WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString WriteStructure

Reading and Writing Data to a File
FileWrite
WriteString
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray
WriteLongIntegerArray


WriteIntegerArray

# WriteIntegerArray

Name:

WriteIntegerArray

Syntax:

   SIGNED_INTEGER WriteIntegerArray( INTEGER file_handle,

INTEGER iArray[m][n] )

Description:

Writes the array to a file starting at the current file position. Two bytes are written, most significant first containing the row dimension of the array, then two more bytes are written, containing the column dimension of the array. Then each integer is written as a two byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are written, because there is a row 0 and a column 0.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadIntegerArray] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

IARRAY is the array whose values are written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

INTEGER iArray[10];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteIntegerArray(nFileHandle, iArray);

      if (iErrorCode \> 0)

        PRINT ( "Array written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadIntegerArray]: ReadIntegerArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteIntegerArray

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteSignedIntegerArray
WriteLongIntegerArray


WriteLongInteger

# WriteLongInteger

Name:

WriteLongInteger

Syntax:

    SIGNED_INTEGER WriteLongInteger ( INTEGER file_handle,

LONG_INTEGER li )

Description:

Writes a long integer to a file starting at the current file position. Four bytes are written, most significant byte first.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray,] [WriteLongIntegerArray], [WriteSignedLongIntegerArray,] [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.\
Use [ReadLongInteger] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

LI is the long integer whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

LONG_INTEGER li;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteLongInteger(nFileHandle, li);

      if (iErrorCode \> 0)

        PRINT ( "Written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray,]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray,]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadLongInteger]: ReadLongInteger.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteLongInteger

Data EndFileOperations File FileOpen FileWrite IF INTEGER LONG_INTEGER PRINT Reading SIGNED_INTEGER StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteLongIntegerArray WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray,
WriteLongIntegerArray


WriteLongIntegerArray

# WriteLongIntegerArray

Name:

WriteLongIntegerArray

Syntax:

    SIGNED_INTEGER WriteLongIntegerArray ( INTEGER file_handle,

LONG_INTEGER ilArray[m][n] )

Description:

Writes the array to a file starting at the current file position. Two bytes are written, most significant first containing the row dimension of the array, then two more bytes are written, containing the column dimension of the array. Then each long  integer is written as a four byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are written, because there is a row 0 and a column 0. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Use [ReadLongIntegerArray] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

ilArray is the array whose values are Write.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an error code.

Example:

(see [File Functions Overview])

INTEGER  nFileHandle, iErrorCode;

LONG_INTEGER ilArray[10];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteLongIntegerArray(nFileHandle, ilArray);

      if (iErrorCode \> 0)

        PRINT ( “Array written to file correctly.\n");

      else

        PRINT ( “Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.03.18 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadLongIntegerArray]: ReadLongIntegerArray.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteLongIntegerArray

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray


WriteSignedInteger

# WriteSignedInteger

Name:

WriteSignedInteger

Syntax:

   SIGNED_INTEGER WriteSignedInteger ( INTEGER file_handle,

SIGNED_INTEGER si )

Description:

Writes a signed integer to a file starting at the current file position. Two bytes are written, most significant first. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadSignedInteger] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SI is the signed integer whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_INTEGER si;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteSignedInteger(nFileHandle, si);

      if (iErrorCode \> 0)

        PRINT ( "Written to file correctly\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadSignedInteger]: ReadSignedInteger.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteSignedInteger

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray
WriteLongIntegerArray


WriteSignedIntegerArray

# WriteSignedIntegerArray

Name:

WriteSignedIntegerArray

Syntax:

   SIGNED_INTEGER WriteSignedIntegerArray ( INTEGER file_handle,

SIGNED_INTEGER isArray[m][n] )

Description:

Writes the array to a file starting at the current file position. Two bytes are written, most significant first containing the row dimension of the array, then two more bytes are Write, containing the column dimension of the array. Then each signed integer is written as a two byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are written, because there is a row 0 and a column 0. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadSigned IntegerArray] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

ISARRAY is the array whose values are Write.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_INTEGER isArray[10][5];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteSignedIntegerArray(nFileHandle, isArray);

      if (iErrorCode \> 0)

        PRINT ( "Array written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: ReadSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadSigned IntegerArray]: ReadSignedIntegerArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteSignedIntegerArray

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteLongIntegerArray


WriteSignedLongInteger

# WriteSignedLongInteger

Name:

WriteSignedLongInteger

Syntax:

  SIGNED_INTEGER WriteSignedLongInteger ( INTEGER file_handle,

SIGNED_LONG_INTEGER sli )

Description:

Writes data to a file starting at the current file position. Each element of the structure is written, without any padding bytes, that might actually be there in memory. Refer to the section titled\
“[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger,] [WriteLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Use [ReadSignedLongInteger] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SLI is the signed long integer whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an error code.

Example:

(see [File Functions Overview])

INTEGER  nFileHandle, iErrorCode;

SIGNED_LONG_INTEGER sli;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteSignedLongInteger(nFileHandle, sli);

      if (iErrorCode \> 0)

        PRINT ( "Written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.03.18 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger,]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadSignedLongInteger]: ReadSignedLongInteger.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteSignedLongInteger

Data EndFileOperations File FileOpen FileWrite IF INTEGER PRINT Reading SIGNED_INTEGER SIGNED_LONG_INTEGER StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteLongIntegerArray WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger,
WriteLongInteger
WriteIntegerArray
WriteSignedIntegerArray
WriteLongIntegerArray


WriteSignedLongIntegerArray

# WriteSignedLongIntegerArray

Name:

WriteSignedLongIntegerArray

Syntax:

 SIGNED_INTEGER WriteSignedLongIntegerArray ( INTEGER file_handle,

SIGNED_LONG_INTEGER sliArray[m][n] )

Description:

Writes the array to a file starting at the current file position. Two bytes are written, most significant first containing the row dimension of the array, then two more bytes are written, containing the column dimension of the array. Then each signed long  integer is written as a four byte quantity, most significant byte first. The integers are stored in row-major order, e.g. all the elements of row 0 first, then the elements of  row 1, etc. Note that there is one more row and one more column than the dimensions that are written, because there is a row 0 and a column 0.. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadSignedLongIntegerArray] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

SLIARRAY is the array whose values are written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

SIGNED_LONG_INTEGER sliArray[10][5];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteSignedLongIntegerArray(nFileHandle, sliArray);

      if (iErrorCode \> 0)

        PRINT ( "Array written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadSignedLongIntegerArray]: ReadSignedLongIntegerArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteSignedLongIntegerArray

Data EndFileOperations File FileOpen FileWrite IF INTEGER PRINT Reading SIGNED_INTEGER SIGNED_LONG_INTEGER StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteSignedLongIntegerArray WriteString


WriteString

# WriteString

Name:

WriteString

Syntax:

    SIGNED_INTEGER WriteString ( INTEGER file_handle, STRING s )

Description:

Writes a string to a file starting at the current file position. Internally, the string is stored as a 2-byte length, most significant byte first, then the actual string bytes.  In the case of a string variable, the total number of bytes written is calculated from the size of the string, not the string allocation size.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions: [FileWrite], [WriteInteger], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadString] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

S is the string whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

STRING s[100];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteString( nFileHandle, s);

      if (iErrorCode \> 0)

        PRINT ( "String written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [WriteStringArray]: WriteStringArray.md
  [ReadString]: ReadString.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteString

Data EndFileOperations File FileOpen FileWrite IF INTEGER PRINT Reading SIGNED_INTEGER STRING StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteLongIntegerArray WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray
WriteLongIntegerArray


WriteStringArray

# WriteStringArray

Name:

WriteStringArray

Syntax:

    SIGNED_INTEGER WriteStringArray ( INTEGER file_handle, STRING s[] )

Description:

Writes a string array to a file starting at the current file position. Internally, the string is stored with the first 2 bytes indicating the total number of strings written, then each string follows as a 2-byte length, most significant byte first, then the actual string bytes.  In the case of a string variable, the total number of bytes is calculated from the size of the string, not the string allocation size.  Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions: [FileWrite], [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray,] [WriteLongIntegerArray,] [WriteSignedLongIntegerArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadStringArray] to read this.

Parameters:

FILE_HANDLE specifies the file handle of the previously opened file (from [FileOpen]).

S is the string whose value is written.

Return Value:

Number of bytes written to the file.  If the return value is negative, it is an [error code].

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, iErrorCode;

STRING s[100][100];

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile", _O_WRONLY );

    IF (nFileHandle \>= 0)

   {

iErrorCode = WriteStringArray( nFileHandle, s);

      if (iErrorCode \> 0)

        PRINT ( "String written to file correctly.\n");

      else

        PRINT ( "Error code %d\n", iErrorCode);

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.03.18 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray,]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray,]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongIntegerArray.md
  [ReadStringArray]: ReadStringArray.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteStringArray

Data EndFileOperations File FileOpen FileWrite IF INTEGER PRINT Reading SIGNED_INTEGER STRING StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString WriteStringArray

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteStructure
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray,


WriteStructure

# WriteStructure

Name:

WriteStructure

Syntax:

     WriteStructure ( INTEGER nFileHandle, STRUCTURE struct [, INTEGER nTotalBytesWritten] )

Description:

Writes data to a file starting at the current file position. Each element of the structure is written, without any padding bytes, that might actually be there in memory. Refer to the section entitled “[Reading and Writing Data to a File]” for a discussion of when to use this function and when to use the related functions:  [FileWrite], [WriteInteger], [WriteString], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray], [WriteSignedIntegerArray], [WriteLongIntegerArray], [WriteSignedLongIntegerArray], [WriteStringArray].

NOTE: Input and Output variables of any kind are not allowed in the file reading and writing functions, just internal variables.

NOTE: Use [ReadStructure] to read this.

 Parameters:

nFileHandle - File handle of the previously opened file (from [FileOpen]).

struct - Structure variable whose data will be written to the file

nTotalBytesWritten - optional argument.  INTEGER variable that will contain the total number of bytes written to the file from the structure.

Return Value:

NONE

Example:

(see [File Functions Overview])

SIGNED_INTEGER  nFileHandle, nTotalBytesWritten;

STRUCTURE PhoneBookEntry

{

   STRING Name[50];

  STRING Address[100];

   STRING PhoneNumber[20];

};

PhoneBookEntry OneEntry;

StartFileOperations();

nFileHandle = FileOpen ( "\\CF0\\MyFile.txt", _O_WRONLY );

if (nFileHandle \>= 0)

{

   WriteStructure( nFileHandle, OneEntry, nTotalBytesWritten );

   if( nTotalBytesWritten \< 0 )

      PRINT ( "Error writing structure.  Error code = %d\n", nTotalBytesWritten );

   else

      PRINT ( "Structure written to file correctly.  Total bytes written = %d\n", nTotalBytesWritten );

}

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [Reading and Writing Data to a File]: Reading_and_Writing_Data_to_a_File.md
  [FileWrite]: FileWrite.md
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongIntegerArray.md
  [WriteIntegerArray]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArray]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray]: WriteSignedLongInteger.md
  [WriteStringArray]: WriteStringArray.md
  [ReadStructure]: Read_Structure.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
WriteStructure

Data EndFileOperations File FileOpen FileWrite INTEGER PRINT Reading SIGNED_INTEGER STRING STRUCTURE StartFileOperations WriteInteger WriteIntegerArray WriteLongInteger WriteLongIntegerArray WriteSignedInteger WriteSignedIntegerArray WriteSignedLongInteger WriteString

Reading and Writing Data to a File
FileWrite
WriteInteger
WriteString
WriteSignedInteger
WriteLongInteger
WriteSignedLongInteger
WriteIntegerArray
WriteSignedIntegerArray
WriteLongIntegerArray


Functions Overview

# Functions Overview

There are a number of different function types in SIMPL+. This topic is provided as a jumping off point in your exploration of the various types of functions that can be implemented in SIMPL+.

[Bit & Byte Functions]

[Data Conversion Functions]

[Language Constructs and Functions]

[Mathematical Functions]

[Random Number Functions]

[String Formatting and Printing Functions]

[String Parsing and Manipulation Functions]

[Time and Date Functions]

[User-Defined Functions]

  [Bit & Byte Functions]: Bit_&_Byte_Functions/Overview.md
  [Data Conversion Functions]: Data_Conversion_Functions/Overview.md
  [Language Constructs and Functions]: Overview.md
  [Mathematical Functions]: Mathematical_Functions/Overview.md
  [Random Number Functions]: Random_Number_Functions/Overview.md
  [String Formatting and Printing Functions]: String_Formatting_&_Printing_Functions/Overview.md
  [String Parsing and Manipulation Functions]: String_Parsing_&_Manipulation_Functions/Overview.md
  [Time and Date Functions]: Time_&_Date_Functions/Overview.md
  [User-Defined Functions]: User_Defined_Functions/User_Defined_Functions_Overview.md

Language Constructs & Functions
Functions Overview

Bit Byte Constructs Conversion Data Date Defined Formatting Functions Language Manipulation Mathematical Number Overview Parsing Printing Random String Time User


# Interfacing to the CEN-OEM via a SIMPL+ Program Overview

When using an X-Generation system to communicate over Ethernet to a CEN-OEM, the CEN-OEM definition is used from the SIMPL Configuration Manager. This symbol has analog inputs, analog outputs, digital inputs, digital outputs, serial inputs, and serial outputs.

When a list of variables such as DIGITAL_INPUTs is declared, they normally start at Digital Input 1 on the symbol and progress linearly up. For some applications, it may be desirable to change the join numbers (leave gaps on the symbol) for a better visual look.

NOTE: These directives apply only to the CEN-OEM device.

[#ANALOG_INPUT_JOIN]

[#ANALOG_OUTPUT_JOIN][][\
#DIGITAL_INPUT_JOIN]

[#DIGITAL_OUTPUT_JOIN]

[#STRING_INPUT_JOIN]

[#STRING_OUTPUT_JOIN]

  [#ANALOG_INPUT_JOIN]: _ANALOG_INPUT_JOIN.md
  [#ANALOG_OUTPUT_JOIN]: _ANALOG_OUTPUT_JOIN.md
  [\
  #DIGITAL_INPUT_JOIN]: _DIGITAL_INPUT_JOIN.md
  [#DIGITAL_OUTPUT_JOIN]: _DIGITAL_OUTPUT_JOIN.md
  [#STRING_INPUT_JOIN]: _STRING_INPUT_JOIN.md
  [#STRING_OUTPUT_JOIN]: _STRING_OUTPUT_JOIN.md

Interfacing to the CEN-OEM via a SIMPL Plus Program


#ANALOG_INPUT_JOIN

# #ANALOG_INPUT_JOIN

Name:

#ANALOG_INPUT_JOIN

Syntax:

    #ANALOG_INPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next ANALOG_INPUT definition to the join number specified by \<constant\>.

Example:

    ANALOG_INPUT SIG1, SIG2, SIG3, SIG4;

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, and SIG4 references Join #4.

    ANALOG_INPUT SIG1, SIG2;

    #ANALOG_INPUT_JOIN 20

    ANALOG_INPUT SIG3, SIG4;

Here, SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, and SIG4 references Join #21.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


#ANALOG_OUTPUT_JOIN

# #ANALOG_OUTPUT_JOIN

Name:

#ANALOG_OUTPUT_JOIN

Syntax:

    #ANALOG_OUTPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next ANALOG_OUTPUT definition to the join number specified by \<constant\>.

Example:

    ANALOG_OUTPUT SIG1, SIG2, SIG3, SIG4;

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, and SIG4 references Join #4.

    ANALOG_OUTPUT SIG1, SIG2;

    #ANALOG_OUTPUT_JOIN 20

    ANALOG_OUTPUT SIG3, SIG4;

SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, and SIG4 references Join #21.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


#DIGITAL_INPUT_JOIN

# #DIGITAL_INPUT_JOIN

Name:

#DIGITAL_INPUT_JOIN

Syntax:

    #DIGITAL_INPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next DIGITAL_INPUT definition to the join number specified by \<constant\>.

Example:

    DIGITAL_INPUT SIG1, SIG2, SIG3, SIG4;

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, and SIG4 references Join #4.

    DIGITAL_INPUT SIG1, SIG2;

    #DIGITAL_INPUT_JOIN 20

    DIGITAL_INPUT SIG3, SIG4;

SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, and SIG4 references Join #21.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


#DIGITAL_OUTPUT_JOIN

# #DIGITAL_OUTPUT_JOIN

Name:

#DIGITAL_OUTPUT_JOIN

Syntax:

    #DIGITAL_OUTPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next DIGITAL_OUTPUT definition to the join number specified by \<constant\>.

Example:

    DIGITAL_OUTPUT SIG1, SIG2, SIG3, SIG4;

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, and SIG4 references Join #4.

    DIGITAL_OUTPUT SIG1, SIG2;

    #DIGITAL_OUTPUT_JOIN 20

    DIGITAL_OUTPUT SIG3, SIG4;

SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, and SIG4 references Join #21.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


#STRING_INPUT_JOIN

# #STRING_INPUT_JOIN

Name:

#STRING_INPUT_JOIN

Syntax:

    #STRING_INPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next STRING_INPUT or BUFFER_INPUT definition to the join number specified by \<constant\>.

Example:

    STRING_INPUT SIG1[20], SIG2[20], SIG3[20], SIG4[20];

    BUFFER_INPUT B1$[20]

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, SIG4 references Join #4, and B1$ references Join#5.

    STRING_INPUT SIG1[20], SIG2[20];

    #STRING_INPUT_JOIN 20

    STRING_INPUT SIG3[20], SIG4[20];

    BUFFER_INPUT B1$[20]

SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, SIG4 references Join #21, and B1$ references Join#22.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


#STRING_OUTPUT_JOIN

# #STRING_OUTPUT_JOIN

Name:

#STRING_OUTPUT_JOIN

Syntax:

    #STRING_OUTPUT_JOIN\<constant\>

Description:

Changes the join number starting with the next STRING_OUTPUT definition to the join number specified by \<constant\>.

Example:

    STRING_OUTPUT SIG1, SIG2, SIG3, SIG4;

In this example, SIG1 references Join #1, SIG2 references Join #2, SIG3 references Join #3, and SIG4 references Join #4.

    STRING_OUTPUT SIG1, SIG2;

    #STRING_OUTPUT_JOIN 20

    STRING_OUTPUT SIG3, SIG4;

SIG1 and SIG2 still reference Join #1 and Join #2, but SIG3 has been changed to reference Join #20, and SIG4 references Join #21.

Version:

CEN-OEM ONLY:  SIMPL v1.50.06 and later


DO - UNTIL

# DO - UNTIL

Name:

DO - UNTIL

Syntax:

    DO

    [{]

      \<statements\>

    [}] UNTIL (\<expression\>);

Description:

This loop performs a set of \<statements\> at least one time and will terminate when \<expression\> evaluates to true. If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that \<expression\> is evaluated each time through the loop.

Example:

    INTEGER X;

    X=0;

    DO

    {

      X = X + 1;

      PRINT("X = %d\n", X);

    }

    UNTIL (X = 25);

In this example, the loop will execute 25 times. The PRINT function will show the value of X after it is incremented to the computer port of the control system.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Looping Constructs
DO - UNTIL


FOR

# FOR

Name:

FOR

Syntax:

    FOR (\<variable\> = \<start_expression\> TO \<end_expression\>

        [STEP \<step_expression\>])

    [{]

      \<statements\>

    [}]

Description:

This loop executes the \<statements\> while \<variable\> iterates from the value of \<start_expression\> to the value of \<end_expression\>. The variable is incremented by \<step_expression\> at the end of the loop, if STEP is specified, else it is incremented by 1. The \<step_expression\> can be negative which will result in the loop counting down. If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that \<start_expression\> and \<end_expression\> are evaluated once before the loop starts and are not re-evaluated during the execution of the loop. If it is defined, \<step_expression\> is evaluated each pass through the loop, so \<step_expression\> may be modified during execution of the loop.

In the 2-Series control systems, the \<step_expression\> cannot change its sign during the execution of the loop. That is, if it is initially a positive number, then it is assumed if it will always count up. If it is negative, it will always count down.

NOTE:  If \<variable\> is set to a value greater than the \<end_expression\> within the body of the FOR loop, the FOR loop will exit when it reaches the end.

At the end of the loop, the loop index has the value of \<end_expression\> + 1 (unless the loop index was modified in the body of the loop).

The comparisons are based on signed numbers, the maximum loop size for a step of one would be from 1 to 32767. If larger indices are needed, for example, from 1 to 60000 a DO-UNTIL or WHILE loop could be used.

Example:

    STRING_INPUT IN$[100];

    INTEGER X;

    FOR (X = 1 TO LEN(IN$))

    {

      PRINT("Character %d of String %s is %s\n", X, IN$,

            MID(IN$, X, 1));

    }

In this example, the loop will iterate through each character of a string and print out the string and its position in the original string.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Looping Constructs
FOR

DO FOR INTEGER LEN MID PRINT STRING_INPUT UNTIL WHILE


Looping Constructs Overview

# Looping Constructs Overview

Loops are used to perform a section of code zero or more times in a row in a given SIMPL+ program. The body of the loop can consist of statements, expressions, function calls, or other loops.

Language Constructs & Functions
Looping Constructs
Overview
Looping Constructs Overview


WHILE

# WHILE

Name:

WHILE

Syntax:

    WHILE(\<expression\>)

    [{]

      \<statements\>

    [}]

Description:

This loop performs a set of \<statements\> as long as \<expression\> does not evaluate to zero. If only one statement is present in the body of the loop, then the { and } characters are not required, but may be used. If more than one statement is present in the loop body, then the { and } characters are mandatory. Note that depending on \<expression\>, the body of the loop may never be executed. Note that \<expression\> is evaluated at the beginning of the loop.

Example:

    INTEGER X;

    X=0;

    WHILE(X \< 25)

    {

      X = X + 1;

      PRINT("X = %d\n", X);

    }

In this example, the loop will execute 25 times. The PRINT function will show the value of X after it is incremented to the computer port of the control system.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Looping Constructs
WHILE


Abs

# Abs

Name:

Abs

Syntax:

INTEGER Abs(INTEGER SOURCE);

INTEGER Abs(SIGNED_INTEGER SOURCE);

Description:

Takes the absolute value of SOURCE. If SOURCE is negative, a positive value is returned. If SOURCE is already positive, the same value is returned.

Parameters:

Takes the absolute value of an INTEGER.

Return Value:

An INTEGER corresponding to the absolute value of SOURCE.

Example:

    DIGITAL_INPUT TRIG;

    INTEGER I, K;

    I=-5;

    CHANGE TRIG

    {

      K=ABS(I);

      PRINT("Original Value = %d, Absolute Value = %d\n", I, K);

    }

The output would be:

    Original Value = -5, Absolute Value = 5

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
ABS
Abs

ABS Abs CHANGE DIGITAL_INPUT INTEGER PRINT SIGNED_INTEGER


Max

# Max

Name:

Max

Syntax:

    INTEGER Max(INTEGER VAL1, INTEGER VAL2)

Description:

Determine the maximum of two values based on an unsigned comparison.

Parameters:

VAL1 and VAL2 are both INTEGER values on which the test is performed.

Return Value:

The maximum of Val1, Val2 after an unsigned comparison is performed. Refer to "Signed vs. Unsigned Arithmetic" on page 5 for a further explanation of how the values are compared.

Example:

    INTEGER X, Y;

    FUNCTION MAIN()

    {

      X = MAX(65535, 0);

      Y = MAX(25, 26);

    }

X would be 65535, and Y would be 26.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
MAX
Max


Min

# Min

Name:

Min

Syntax:

    INTEGER Min(INTEGER VAL1, INTEGER VAL2)

Description:

Determine the minimum of two values based on an unsigned comparison.

Parameters:

VAL1 and VAL2 are both INTEGER values on which the test is performed.

Return Value:

The minimum of Val1, Val2 after an unsigned comparison is performed. Refer to "Signed vs. Unsigned Arithmetic" for a further explanation of how the values are compared.

Example:

    INTEGER X, Y;

    FUNCTION MAIN()

    {

      X = MIN(65535, 0);

      Y = MIN(25, 26);

    }

X would be 0, and Y would be 25.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
MIN
Min


MulDiv

# MulDiv

Name:

MulDiv

Syntax:

    INTEGER MulDiv(INTEGER VAL1, INTEGER VAL2, INTEGER VAL3)

Description:

Computes the result (VAL1 \* VAL2)/VAL3.

Parameters:

VAL1, VAL2, and VAL3 are INTEGER values.

Return Value:

A 16-bit integer is returned based on the above equation. The arithmetic operations are performed using unsigned arithmetic. Note that 32-bit math is used internally, so that if VAL1\*VAL2 is greater than a 16-bit number, accuracy is maintained. If the final result is greater than 16-bits, the lower 16-bits are returned.

Example:

    INTEGER X, Y;

    FUNCTION MAIN()

    {

      X = 1970;

      Y = 40;

      PRINT("The result of (%d \* %d)/25 = %d\n", X, Y,

      MULDIV(X, Y, 25);

    }

The PRINT statement would show the result as being 3152. In this case, X\*Y is greater than a 16-bit number, but accuracy is maintained due to the use of 32-bit arithmetic internally.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
MULDIV
MulDiv

FUNCTION INTEGER MAIN MULDIV MulDiv PRINT


Mathematical Functions Overview

# Mathematical Functions Overview

These functions perform general mathematical operations in a given SIMPL+ program by operating on one or more numerical arguments and returning an INTEGER as a result.

Language Constructs & Functions
Mathematical Functions
Overview
Mathematical Functions Overview


SMAX

# SMAX

Name:

SMax

Syntax:

    INTEGER SMax(INTEGER VAL1, INTEGER VAL2)

Description:

Determine the maximum of two values based on a signed comparison.

Parameters:

VAL1 and VAL2 are both INTEGER values on which the test is performed.

Return Value:

The maximum of Val1, Val2 after a signed comparison is performed. Refer to "Signed vs. Unsigned Arithmetic" for a further explanation of how the values are compared.

Example:

    INTEGER X, Y;

    FUNCTION MAIN()

    {

      X = SMAX(65535, 0);

      Y = SMAX(25, 26);

    }

X would be 0 (65535 interpreted as -1), and Y would be 26.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
SMAX