SendMail (Part 1)

# SendMail

Name:

SendMail

Syntax:

    SIGNED_INTEGER SendMail( STRING Server,

                     STRING UserLogonName,

                     STRING UserLogonPassword,

                     STRING From,

                     STRING To,

                     STRING CC,

                     STRING Subject,

                     STRING Message       )

Description:

Send an email message using SMTP protocol.

Parameters:

Server - Required.  Specifies address of the mail server.  It can either be an IP address in dot-decimal notation (ex: 192.168.16.3) or a name to be resolved with a DNS server (ex:  mail.myisp.com).  If a name is given, the control system must be configured with a DNS server (ADDDNS console command).   Maximum field length: 40.

UserLogonName - Optional, but use an empty string in its place if authentication is not required.   If the mail server requires authentication, UserLogonName indicates the user name of the sender for the mail server.   An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

UserLogonPassword - Optional, but put an empty string in it's place if not required.   If the mail server requires authentication, UserLogonPassword indicates the password of the sender for the mail server.  An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

From -  Required.  Specifies the e-mail address of the sender in the a@b.com format.  Only one email address is allowed.  Aliases or nicknames are not supported.  This argument is mandatory.  Maximum field length: 242.

To - Required.  Specifies the e-mail address of the recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  This argument is mandatory.  Maximum field length: 65535.

CC - Optional, but use an empty string to indicate that there are no recipients.  Specifies the e-mail address of the carbon copy recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  Maximum field length: 65535.

Subject - Optional, but use an empty string to indicate that there is no subject.  Specifies the subject of the email message.  Maximum field length: 989.

Message - Optional, but use an empty string to indicate an empty message.  Specifies the body of the email message.    Maximum field length: 65535.

Return Value:

0 if successful.   Otherwise,  [Email Return Error Code] is returned. Negative return error codes indicate that no part of the email was sent (example:  user logon password was incorrect).  Positive return error codes indicate a failure (example: one or more recipient email addresses was invalid), but the email was still sent.  In the event of more than one failure, the return error code of the first failure is returned.

Example:

         SIGNED_INTEGER nErr;

Language Constructs & Functions
Email Functions
SendMail
SendMail


SendMail (Part 2)

    nErr = SendMail( "192.168.16.3",

                     "UserLogonName",

                     "UserLogonPassword",

                     "SenderEmailAddress@crestron.com",

                     "RecipientEmailAddress@crestron.com",

                     "ccEmailAddress@crestron.com",

                     "This is the subject",

                     "This is the message" );

   if ( nErr \< 0 )

               Print( "Error sending email\n" );

   else

               Print( "SendMail successful!\n );

Version:

X Generation:  Not Supported

2-Series:  SIMPL v2.03.18 and later

  [Email Return Error Code]: Email_Function_Return_Error_Codes.md

Code Email Error Part Print Return SendMail

In the event of more than one failure, the return error code of the first failure is returned. Example:

         SIGNED_INTEGER nErr;


SendMailAdvance (Part 1)

# SendMailAdvance

Name:

SendMailAdvance

Syntax:

SIGNED_INTEGER SendMailAdvance( STRING Server,

INTEGER PortNumber

STRING UserLogonName,

STRING UserLogonPassword,

STRING From,

STRING To,

STRING CC,

STRING Subject,

STRING Message,

INTEGER NumberOfAttachments,

STRING Attachment )

Description:

Programatically sends an email message to the specified IP address on the specified port using the SMTP protocol.

Parameters:

Server - Required.  Specifies address of the mail server.  It can either be an IP address in dot-decimal notation (ex: 192.168.16.3) or a name to be resolved with a DNS server (ex:  mail.myisp.com).  If a name is given, the control system must be configured with a DNS server (ADDDNS console command).   Maximum field length: 40.

PortNumber - Required. Specifies the port number used to send the email.

UserLogonName - Optional.  Use an empty string in its place if authentication is not required.   If the mail server requires authentication, UserLogonName indicates the user name of the sender for the mail server.   An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

UserLogonPassword - Optional.  Use an empty string in it's place if not required.   If the mail server requires authentication, UserLogonPassword indicates the password of the sender for the mail server.  An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

From -  Required.  Specifies the e-mail address of the sender in the a@b.com format.  Only one email address is allowed.  Aliases or nicknames are not supported.  This argument is mandatory.  Maximum field length: 242.

To - Required.  Specifies the e-mail address of the recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  This argument is mandatory.  Maximum field length: 65535.

CC - Optional.  An empty string indicates that there are no recipients.  Specifies the e-mail address of the carbon copy recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  Maximum field length: 65535.

Subject - Optional.  An empty string indicates that there is no subject.  Specifies the subject of the email message.  Maximum field length: 989.

Message - Optional.  An empty string indicates an empty message.  Specifies the body of the email message.    Maximum field length: 65535.

NumberOfAttachments - Optional.  0 specifies that there are no attachments.  Specifies the number of attachments to be sent.

Attachment - Optional.  An empty string indicates that no attachments are to be sent.  Specifies the files to be attached. Multiple filenames may be specified, delimited by ';'. Max field length is 65534.

Return Value:

Language Constructs & Functions
Email Functions
SendMailAdvance
SendMailAdvance

INTEGER Part SIGNED_INTEGER STRING SendMailAdvance


SendMailAdvance (Part 2)

0 if successful.   Otherwise,  Email Return [Error Code] is returned. Negative return [error codes][Error Code] indicate that no part of the email was sent (example:  user logon password was incorrect).  Positive return [error codes][Error Code] indicate a failure (example: one or more recipient email addresses was invalid), but the email was still sent.  In the event of more than one failure, the return [error code] of the first failure is returned.

Example:

SIGNED_INTEGER nErr;

    nErr = SendMailAdvance( "192.168.16.3",

 80

"UserLogonName",

"UserLogonPassword",

"SenderEmailAddress@crestron.com",

"RecipientEmailAddress@crestron.com",

"ccEmailAddress@crestron.com",

"This is the subject",

"This is the message",

2,

"\\CF0\\test.pdf;\\CF0\\test.img" );

   if ( nErr \< 0 )

               Print( "Error sending email\n" );

   else

               Print( "SendMail successful!\n );

NOTE: If the attachment count is 0 but the "attachment" parameter is not empty, OR if the attachment count is positive, but the "attachment" parameter is empty, an SMTP_INV_PARM error will be returned with the following error in the error log, ""Bad Attachment parameters to SendMail". \
\
NOTE: If the attachment count does not match the number of files in the "attachment" parameter (separated by a delimiter) then the following will happen.  If the attachment count parameter is less than the number of files specified in the "attachment" parameter, then the function will attempt to send out valid files specified by the attachment count parameter(INTEGER).\
\
NOTE: If the attachment count parameter is more than the number of files specified in the "attachment" parameter, then the function will attempt to send the valid files specified by the "attachment" parameter(STRING).

 Version:

X Generation:  Not Supported

2-Series:  SIMPL v2.05.17 and later. CUZ 4.001 or later.

  [Error Code]: Email_Function_Return_Error_Codes.md

Code Error INTEGER Part Print SIGNED_INTEGER STRING SendMailAdvance

Max field length is 65534. Return Value:


SendMailWithAttachments (Part 1)

# SendMailWithAttachments

Name:

SendMailWithAttachments

Syntax:

SIGNED_INTEGER SendMailWithAttachments( STRING Server,

STRING UserLogonName,

STRING UserLogonPassword,

STRING From,

STRING To,

STRING CC,

STRING Subject,

STRING Message,

INTEGER NumberOfAttachments,

STRING Attachment )

Description:

Send an email message with attachments using SMTP protocol.

Parameters:

Server - Required.  Specifies address of the mail server.  It can either be an IP address in dot-decimal notation (ex: 192.168.16.3) or a name to be resolved with a DNS server (ex:  mail.myisp.com).  If a name is given, the control system must be configured with a DNS server (ADDDNS console command).   Maximum field length: 40.

UserLogonName - Optional.  Use an empty string in its place if authentication is not required.   If the mail server requires authentication, UserLogonName indicates the user name of the sender for the mail server.   An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

UserLogonPassword - Optional.  Use an empty string in it's place if not required.   If the mail server requires authentication, UserLogonPassword indicates the password of the sender for the mail server.  An empty string indicates that authentication is not required.  Only "clear text" authentication is implemented. "Clear text" refers to the authentication method used by the mail server. If the mail server requires a higher level authentication, mail can not be sent to the mail server.  Maximum field length: 254.

From -  Required.  Specifies the e-mail address of the sender in the a@b.com format.  Only one email address is allowed.  Aliases or nicknames are not supported.  This argument is mandatory.  Maximum field length: 242.

To - Required.  Specifies the e-mail address of the recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  This argument is mandatory.  Maximum field length: 65535.

CC - Optional.  An empty string indicates that there are no recipients.  Specifies the e-mail address of the carbon copy recipient(s) in the a@b.com format.  Multiple recipients may be specified delimited with a ";".  Maximum field length: 65535.

Subject - Optional.  An empty string indicates that there is no subject.  Specifies the subject of the email message.  Maximum field length: 989.

Message - Optional.  An empty string indicates an empty message.  Specifies the body of the email message.    Maximum field length: 65535.

NumberOfAttachments - Optional.  0 specifies that there are no attachments.  Specifies the number of attachments to be sent.

Attachment - Optional.  An empty string indicates that no attachments are to be sent.  Specifies the files to be attached. Multiple filenames may be specified, delimited by ';'. Max field length is 65534.

Return Value:

Language Constructs & Functions
Email Functions
SendMailWithAttachments
SendMailWithAttachments

INTEGER Part SIGNED_INTEGER STRING SendMailWithAttachments


SendMailWithAttachments (Part 2)

0 if successful.   Otherwise,  Email Return [Error Code] is returned. Negative return [error codes][Error Code] indicate that no part of the email was sent (example:  user logon password was incorrect).  Positive return [error codes][Error Code] indicate a failure (example: one or more recipient email addresses was invalid), but the email was still sent.  In the event of more than one failure, the return [error code] of the first failure is returned.

Example:

SIGNED_INTEGER nErr;

    nErr = SendMailWithAttachments( "192.168.16.3",

"UserLogonName",

"UserLogonPassword",

"SenderEmailAddress@crestron.com",

"RecipientEmailAddress@crestron.com",

"ccEmailAddress@crestron.com",

"This is the subject",

"This is the message",

2,

"\\CF0\\test.pdf;\\CF0\\test.img" );

   if ( nErr \< 0 )

               Print( "Error sending email\n" );

   else

               Print( "SendMail successful!\n );

NOTE: If the attachment count is 0 but the "attachment" parameter is not empty, OR if the attachment count is positive, but the "attachment" parameter is empty, an SMTP_INV_PARM error will be returned with the following error in the error log, ""Bad Attachment parameters to SendMail". \
\
NOTE: If the attachment count does not match the number of files in the "attachment" parameter (separated by a delimiter) then the following will happen.  If the attachment count parameter is less than the number of files specified in the "attachment" parameter, then the function will attempt to send out valid files specified by the attachment count parameter(INTEGER).\
\
NOTE: If the attachment count parameter is more than the number of files specified in the "attachment" parameter, then the function will attempt to send the valid files specified by the "attachment" parameter(STRING).

 Version:

X Generation:  Not Supported

2-Series:  SIMPL v2.05.17 and later

  [Error Code]: Email_Function_Return_Error_Codes.md

Code Error INTEGER Part Print SIGNED_INTEGER STRING SendMailWithAttachments


ASCII

# ASCII

Name:

ASCII

Syntax:

    ASCII

NOTE: This is not a declaration but a declaration modifier. It works only in conjunction with the STRING declaration keyword.

Description:

The encoding of the string will be forced to ASCII if the declaration is preceded by the ASCII modifier.

Example:

 ASCII string s[100];

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

Language Constructs & Functions
Encoding
ASCII


GetEncoding

# GetEncoding

Name:

GetEncoding

Syntax:

    GetEncoding(STRING myString);

Description:

Returns the encoding of a string. The following constants are declared to help comparison:

ENCODING_ASCII – Returned when the encoding of the string is set to ASCII.

ENCODING_UTF16 – Returned when the encoding of the string is set to [UTF16].

Any other return value should be treated as an error.

Parameters:

myString is a string declared in the program. This can either be a global string or a local string.

Return Value:

An INTEGER containing the encoding of the string. The value of the return value can either be ASCII or UTF16.

Example:

   In this example, the string encoding is retrieved from a string an appropriate string is printed on the console.

Function GetEncodingFunction()

{

   INTEGER encoding;

   STRING  myString[10];

   encoding = getencoding(myString);

   if (encoding = ENCODING_ASCII)

     print ("ASCII\r\n");

   else if (encoding = ENCODING_UTF16)

     print ("UTF16\r\n");

   else

     print ("Error getting encoding\r\n");

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

  [UTF16]: UTF16_Unicode_Encoding.md

Language Constructs & Functions
Encoding
GETENCODING
GetEncoding

GetEncoding GetEncodingFunction INTEGER STRING UTF16


INHERIT

# INHERIT

Name:

INHERIT

Syntax:

    INHERIT

NOTE: This is not a declaration but a declaration modifier. It works only in conjunction with the STRING declaration keyword.

Description:

The encoding of the string will be forced to the module’s default inherited encoding type.  Inherited encoding types can either be from the parent module or calling program.  These are both set by the compiler directives, [#ENCODING_INHERIT_FROM_PARENT] and [#ENCODING_INHERIT_FROM_PROGRAM].

Example:

 INHERIT string s[100];

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [#ENCODING_INHERIT_FROM_PARENT]: _ENCODING_INHERIT_FROM_PARENT.md
  [#ENCODING_INHERIT_FROM_PROGRAM]: _ENCODING_INHERIT_FROM_PROGRAM.md

Language Constructs & Functions
Encoding
Inherit
INHERIT


SetEncoding

# SetEncoding

Name:

SetEncoding

Syntax:

    SetEncoding(STRING myString, ENCODING_TYPE encoding);

Description:

Sets the encoding of a string. Encoding can only be one the following types:

ENCODING_ASCII – Encoding of the string is set to ASCII.

ENCODING_UTF16 – Encoding of the string is set to [UTF16].

ENCODING_INHERIT – Encoding of the string is set to the inherited encoding of the module. The encoding directive is used to set the encoding.

Parameters:

myString is a string declared in the program. This can either be a global string or a local string.

Encoding can either be ENCODING_ASCII, ENCODING_UTF16 or ENCODING_INHERIT.

Return Value:

None.

Example:

   In this example, the string encoding is set on a string.

Function SetEncodingFunction()

{

   STRING  myString[10];

   // Set encoding to ASCII

   setencoding(myString, ENCODING_ASCII);

   // Set encoding to UTF16

   setencoding(myString, ENCODING_UTF16);

   // Set encoding to default encoding inherited using the encoding directive.

   setencoding(myString, ENCODING_INHERIT);

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

  [UTF16]: UTF16_Unicode_Encoding.md

Language Constructs & Functions
Encoding
SetEncoding

STRING SetEncoding SetEncodingFunction UTF16


ToASCII()

# ToASCII()

Name:

ToASCII

Syntax:

    STRING ToASCII(STRING myString);

Description:

Converts the encoding of a [UTF16] string to ASCII.

Parameters:

myString is a string declared in the program. This can either be a global string or a local string.

Return Value:

A reference to myString after conversion.

Example:

   In this example, the string encoding is converted to ASCII.

Function ConvertEncodingToASCII()

{

  UTF16 STRING utf16String[10];

  INTEGER encoding;

  TOASCII(utf16String);

  encoding = getencoding(utf16String);

  if (encoding = ENCODING_ASCII)

    print ("ASCII\r\n");

  else if (encoding = ENCODING_UTF16)

    print ("UTF16\r\n");

  else

    print ("Error getting encoding\r\n");

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

  [UTF16]: UTF16_Unicode_Encoding.md

Language Constructs & Functions
Encoding
ToASCII
ToASCII()

ConvertEncodingToASCII INTEGER STRING TOASCII ToASCII UTF16


ToUTF16

# ToUTF16

Name:

ToUTF16

Syntax:

    STRING ToUTF16 (STRING myString);

Description:

Converts the encoding of the string to [UTF16].

Parameters:

myString is a string declared in the program. This can either be a global string or a local string.

Return Value:

A reference to myString after conversion.

Example:

 In this example, the string encoding is converted to UTF16.

Function ConvertEncodingToUTF16()

{

  ASCII STRING ascString[10];

  INTEGER encoding;

  TOUTF16(ascString);

  encoding = getencoding(ascString);

  if (encoding = ENCODING_ASCII)

    print ("ASCII\r\n");

  else if (encoding = ENCODING_UTF16)

    print ("UTF16\r\n");

  else

    print ("Error getting encoding\r\n");

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

  [UTF16]: UTF16_Unicode_Encoding.md

Language Constructs & Functions
Encoding
ToUTF16


UTF16

# UTF16

Name:

UTF16

Syntax:

    UTF16

NOTE: This is not a declaration but a declaration modifier. It works only in conjunction with the STRING declaration keyword.

Description:

The encoding of the string will be forced to UTF16 if the declaration is preceded by the UTF16 modifier.

Example:

 UTF16 string s[100];

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

Language Constructs & Functions
Encoding
UTF16


UTF16 Unicode Encoding

# UTF16 Unicode Encoding

Systems may either be ASCII compliant or use Unicode.

Unicode allows for characters that are greater than 8 bits, which means that character sets other than the standard US character sets may be used.  Typically this would be for talking to a touch screen using other character sets (Chinese, Japanese, etc.)

In Unicode terminology, it is commonplace to express a character in terms of a “Codepoint”.  This allows someone to reference a particular character without worrying about the underlying encoding mechanism.   A codepoint is specified as U+{4 digits} or U+{6 digits}.

In the 2 series, strings are encoded as a series of bytes, and so there is no concept of encoding for Unicode.

In the 3 series, strings are encoded as a series of words. Therefore a string expressed in SIMPL as “\x25\x26\x27” is actually stored as 3 words; 0x0025, 0x0026, and 0x0027. Since the system deals with bytes at the lowest level, Crestron has decided to encode as in a format known as “Little Endian” – which is the Low byte of a word followed by the High byte of a word.   The actual storage on a byte level is 0x26 0x00 0x26 0x00 0x27 0x00.

NOTE: A word is another name for a 16b value, much like a byte is a name for an 8b value.

In the 3 Series, Crestron has chosen to use UTF-16LE as our particular encoding method for Unicode.  LE stands for Little Endian to reflect the above storage concept.

Language Constructs & Functions
Encoding
UTF16 Unicode Encoding


#ENCODING_ASCII

# #ENCODING_ASCII

Name:

#ENCODING_ASCII

Syntax:

    #ENCODING_ASCII

Description:

An encoding directive is used to indicate the default encoding of strings if the encoding is not specified by an encoding keyword. The #ENCODING_ASCII directive will ensure that any strings in the SIMPL+ module without explicit encoding keywords are marked with ASCII encoding.

NOTE: If an encoding directive is not specified in a file, all strings will default to ASCII encoding.

Example:

   #ENCODING_ASCII

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

Language Constructs & Functions
Encoding
ENCODING ASCII
#ENCODING_ASCII


#ENCODING_INHERIT_FROM_PARENT

# #ENCODING_INHERIT_FROM_PARENT

Name:

#ENCODING_INHERIT_FROM_PARENT

Syntax:

    #ENCODING_INHERIT_FROM_PARENT

Description:

An encoding directive is used to indicate the default encoding of strings if the encoding is not specified by an encoding keyword. The #ENCODING_INHERIT_FROM_PARENT directive will ensure that any strings in the SIMPL+ module without explicit encoding keywords are marked with default encoding of the parent of this module.

NOTE: If an encoding directive is not specified in a file, all strings will default to ASCII encoding.

Example:

   #ENCODING_INHERIT_FROM_PARENT

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

Language Constructs & Functions
Encoding
ENCODING INHERIT FROM PARENT
#ENCODING_INHERIT_FROM_PARENT


#ENCODING_INHERIT_FROM_PROGRAM

# #ENCODING_INHERIT_FROM_PROGRAM

Name:

#ENCODING_INHERIT_FROM_PROGRAM

Syntax:

    #ENCODING_INHERIT_FROM_PROGRAM

Description:

An encoding directive is used to indicate the default encoding of strings if the encoding is not specified by an encoding keyword. The #ENCODING_INHERIT_FROM_PROGRAM directive will ensure that any strings in the SIMPL+ module without explicit encoding keywords are marked with default encoding of the parent of this module.

NOTE: If an encoding directive is not specified in a file, all strings will default to ASCII encoding.

Example:

   #ENCODING_INHERIT_FROM_PROGRAM

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

Language Constructs & Functions
Encoding
ENCODING INHERIT FROM PROGRAM
#ENCODING_INHERIT_FROM_PROGRAM


#ENCODING_UTF16

# #ENCODING_UTF16

Name:

# ENCODING_UTF16

Syntax:

    #ENCODING_UTF16

Description:

An encoding directive is used to indicate the default encoding of strings if the encoding is not specified by an encoding keyword. The #ENCODING_UTF16 directive will ensure that any strings in the SIMPL+ module without explicit encoding keywords are marked with [UTF16] encoding.

NOTE: If an encoding directive is not specified in a file, all strings will default to ASCII encoding.

Example:

   #ENCODING_UTF16

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: Supported

4-Series: Supported

  [UTF16]: UTF16_Unicode_Encoding.md

Language Constructs & Functions
Encoding
ENCODING UTF16
#ENCODING_UTF16


#IF_SERIES2

# #IF_SERIES2

Name:

# IF_SERIES2

Syntax:

    #IF_SERIES2 \<statements\> [ #ELSE \<statements\> ] #ENDIF

Description:

When compiling for different control system targets, it might be desirable to have each target execute a different portion of code.  Reasons for this might be new or obsolete functions or different performance characteristics in each control system. Using this compiler directive will cause the compiler to only include the statements for the 2-series control system.  The #ELSE block is optional and may be used if a different set of code should be executed when the 2-series is not the target control system.

Example:

   #IF_SERIES2

Function FunctionOne()

{

}

#ENDIF

#IF_SERIES2

Function FunctionTwo()

{

}

#ELSE

Function FunctionThree()

{

}

#ENDIF

Function FunctionFour()

{

#IF_SERIES2

// some code

#ELSE

// some other code

#ENDIF

}

Version:

X Generation:  Not Supported

2-Series:

3-Series:

Language Constructs & Functions
Encoding
IF SERIES2
#IF_SERIES2

ELSE FunctionFour FunctionOne FunctionThree FunctionTwo IF_SERIES2


#IF_SERIES3

# #IF_SERIES3

Name:

# IF_SERIES3

Syntax:

    #IF_SERIES3 \<statements\> [ #ELSE \<statements\> ] #ENDIF

Description:

When compiling for different control system targets, it might be desirable to have each target execute a different portion of code.  Reasons for this might be new or obsolete functions or different performance characteristics in each control system. Using this compiler directive will cause the compiler to only include the statements for the 3-series control system.  The #ELSE block is optional and may be used if a different set of code should be executed when the 3-series is not the target control system.

NOTE: During a compilation for 4-series control systems SIMPL will issue a warning whenever a #IF_SERIES3 directive is found.\
\
As any logic contained in the #IF_SERIES3 block WILL NOT be compiled for 4-series control systems make sure that logic intended for 4-series control system is outside of the #IF_SERIES3 block.\

Example:

   #IF_SERIES3

Function FunctionOne()

{

}

#ENDIF

#IF_SERIES3

Function FunctionTwo()

{

}

#ELSE

Function FunctionThree()

{

}

#ENDIF

Function FunctionFour()

{

#IF_SERIES3

// some code

#ELSE

// some other code

#ENDIF

}

Language Constructs & Functions
Encoding
IF SERIES3
#IF_SERIES3

ELSE FunctionFour FunctionOne FunctionThree FunctionTwo IF_SERIES3


#IF_SERIES4

# #IF_SERIES4

Name:

# IF_SERIES4

Syntax:

    #IF_SERIES4 \<statements\> [ #ELSE \<statements\> ] #ENDIF

Description:

When compiling for different control system targets, it might be desirable to have each target execute a different portion of code.  Reasons for this might be new or obsolete functions or different performance characteristics in each control system. Using this compiler directive will cause the compiler to only include the statements for the 4-series control system.  The #ELSE block is optional and may be used if a different set of code should be executed when the 4-series is not the target control system.

The #IF_SERIES4 keyword is ignored and the SIMPL+ module should compile without issues when the SIMPL+ module target control system class is any of the following:

- 2-Series only
- 3-Series only
- 2-Series and 3-Series

Example:

   #IF_SERIES4

Function FunctionOne()

{

}

#ENDIF

#IF_SERIES4

Function FunctionTwo()

{

}

#ELSE

Function FunctionThree()

{

}

#ENDIF

Function FunctionFour()

{

#IF_SERIES4

// some code

#ELSE

// some other code

#ENDIF

}

Version:

4-Series: SIMPL v. 4.14.xx

Language Constructs & Functions
Encoding
IF SERIES4
#IF_SERIES4

ELSE FunctionFour FunctionOne FunctionThree FunctionTwo IF_SERIES4


CHANGE

# CHANGE

Name:

CHANGE

Syntax:

    CHANGE \<variable_name1\> [, \<variable_name2\> ...]

    {

      [Local Variable Definitions]

      \<statements\>

    }

Description:

The CHANGE event is called when a DIGITAL_INPUT transitions from low to high or high to low, or when an ANALOG_INPUT or STRING_INPUT changes.

\<variable_name\> may be either a DIGITAL_INPUT, ANALOG_INPUT, or STRING_INPUT  type. If it is a DIGITAL_INPUT, the statements between { and } will be executed when the input transitions from low to high or high to low. If it is an ANALOG_INPUT or STRING_INPUT, the statements between { and } will be executed whenever the variable changes. Note that for an ANALOG_INPUT or STRING_INPUT, the same value re-issued will also cause the CHANGE to activate.

When using ANALOG_INPUT, BUFFER_INPUT, DIGITAL_INPUT, or STRING_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to "[GetLastModifiedArrayIndex]" to determine which element actually changed. Use isSignalDefined to make sure that you send data only to outputs that exist or take input from signals that exist.

When listing multiple variable names, the names can be put on the same line or broken up into several CHANGE statements for readability.

(See also [StackedEvents] and [THREADSAFE])

Example:

    STRING_INPUT some_data$[100];

    ANALOG_OUTPUT level;

    CHANGE some_data$

    {

      level=48;

    }

When the STRING_INPUT changes, the ANALOG_OUTPUT level will have the value 48 put into it. If the same data comes in on some_data$, the CHANGE block is executed again.

    ANALOG_INPUT ThingsToAdd[20];

    ANALOG_OUTPUT Sum;

    INTEGER I, Total;

    CHANGE ThingsToAdd

    {

      Total=0;

      FOR(I=0 to 20)

if (isSignalDefined (ThingsToAdd[I]))

        Total = Total + ThingsToAdd[I];

      Sum = Total;

    }

In this example, an array is used to hold elements to add. When any element of the array changes, the total is recomputed and issued on an analog output variable.

Version:

X Generation:

SIMPL v1.20.01 and later

SIMPL v1.50.06 and later, ANALOG_INPUT, BUFFER_INPUT, DIGITAL_INPUT, and STRING_INPUT arrays as \<variable_name\>

2-Series:

SIMPL v2.01.05 and later [Same as X Generation SIMPL v1.50.06] and Local Variables allowed within CHANGE statements.

  [GetLastModifiedArrayIndex]: ../Array_Operations/GetLastModifiedArrayIndex.md
  [StackedEvents]: Stacked_Events.md
  [THREADSAFE]: THREADSAFE.md

Language Constructs & Functions
Events
CHANGE


EVENT

# EVENT

Name:

EVENT

Syntax:

    EVENT

    {

      [Local Variable Definitions]

      \<statements\>

    }

Description:

Executes the defined \<statements\> anytime one of the inputs to the SIMPL+ symbol changes. It is similar to having a CHANGE statement listed for every input, and each change is set up to execute a common block of code.

(see also [StackedEvents] and [THREADSAFE])

Example:

    ANALOG_INPUT level1, level2, level3;

    STRING_INPUT extra$[2][20];

    STRING_OUTPUT OUT$;

    EVENT

    {

      OUT$=extra$[0]+extra$[1]+CHR(level1)+CHR(level2)+CHR(level3);

    }

In this example, when the ANALOG_INPUTs level1, level2, level3, or level4 have any change or the STRING_INPUT array extra$ has changed, the STRING_OUTPUT OUT$ will be recomputed and reissued.

Version:

X Generation:

SIMPL v1.20.01 and later

2-Series

SIMPL v2.01.05 and later [Same as X Generation v1.20.01], however Local variables are allowed within EVENT statements.

  [StackedEvents]: Stacked_Events.md
  [THREADSAFE]: THREADSAFE.md

Language Constructs & Functions
Events
EVENT


Events Overview

# Events Overview

SIMPL+ is an event driven language. There are eight functions, or event handlers, which deal with activating events in a given SIMPL+ program; CHANGE, CONNECT, DISCONNECT, EVENT, PUSH, RECEIVE, RELEASE and STATUS.

| Event            | Description                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| CHANGE           | The CHANGE event is called when a DIGITAL_INPUT transitions from low to high or high to low, or when an ANALOG_INPUT or STRING_INPUT changes.                                                                                |
| EVENT            | Executes the defined <statements> anytime one of the inputs to the SIMPL+ symbol changes. It is similar to having a CHANGE statement listed for every input, and each change is set up to execute a common block of code.            |
| PUSH             | PUSH is executed when a DIGITAL_INPUT transitions from low to high.                                                                                |
| RELEASE          | RELEASE is executed when a DIGITAL_INPUT transitions from high to low.                                                                                |
| SOCKETCONNECT    | The SOCKETCONNECT event is called when a socket connection is completed on a TCP_CLIENT or TCP_SERVER variable.                                                                                |
| SOCKETDISCONNECT | The SOCKETDISCONNECT event is called when a TCP_CLIENT or TCP_SERVER socket is disconnected.                                                                                |
| SOCKETRECEIVE    | The SOCKETRECEIVE event is called when a TCP_CLIENT or TCP_SERVER socket receives data.                                                                                |
| SOCKETSTATUS     | The SOCKETSTATUS event is called when the status of a TCP_CLIENT or TCP_SERVER socket changes.                                                                                |
| THREADSAFE       | When using the THREADSAFE keyword before an event (such as PUSH, RELEASE, CHANGE) the event is prevented from retriggering, until the entire code block in the event has executed. Events prevented from triggering WILL be dropped. |

Language Constructs & Functions
Events
Overview
Events Overview

ANALOG_INPUT CHANGE DIGITAL_INPUT EVENT Events Overview PUSH RELEASE STRING_INPUT THREADSAFE


PUSH

# PUSH

Name:

PUSH

Syntax:

    PUSH \<variable_name1\> [, \<variable_name2\> ...]

    {

       [Local Variable Definitions]

       \<statements\>

    }

Description:

PUSH is executed when a DIGITAL_INPUT transitions from low to high.

\<variable_name\> is a DIGITAL_INPUT type. On the rising edge of \<variable_name\>, the statements between the opening { and closing } are executed.

When using DIGITAL_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to [GetLastModifiedArrayIndex] for a method of detecting a change to an individual element.

When listing multiple variable names, the names can be put on the same line or broken up into several PUSH statements for readability.

(see also [StackedEvents] AND [THREADSAFE])

Example:

    DIGITAL_INPUT trigger;

    STRING_OUTPUT output$;

    PUSH trigger

    {

      output$ = "Hello, World!";

    }

In this example, when the DIGITAL_INPUT trigger transitions from low to high, the STRING_OUTPUT output$ will have the string "Hello, World!" put into it.

Version:

X Generation:

SIMPL v1.20.01 and later

SIMPL v1.50.06 and later, DIGITAL_INPUT arrays as \<variable_name\>

2-Series:

SIMPL v2.01.05 and later [Same as X Generation SIMPL v1.50.06] and Local Variables allowed within PUSH Statements.

  [GetLastModifiedArrayIndex]: ../Array_Operations/GetLastModifiedArrayIndex.md
  [StackedEvents]: Stacked_Events.md
  [THREADSAFE]: THREADSAFE.md

Language Constructs & Functions
Events
PUSH

DIGITAL_INPUT GetLastModifiedArrayIndex PUSH STRING_OUTPUT StackedEvents THREADSAFE


RELEASE

# RELEASE

Name:

RELEASE

Syntax:

    RELEASE \<variable_name1\> [, \<variable_name2\> ...]

    {

      [Local Variable Definitions]

      \<statements\>

    }

Description:

RELEASE is executed when a DIGITAL_INPUT transitions from high to low.

\<variable_name\> is a DIGITAL_INPUT type. On the trailing edge of \<variable_name\>, the statements between the opening { and closing } are executed.

When using DIGITAL_INPUT arrays, only a change in the entire array can be detected, not an individual element. Refer to [GetLastModifiedArrayIndex] for a method of detecting a change to an individual element.

When listing multiple variable names, the names can be put on the same line or broken up into several RELEASE statements for readability.

(See also [StackedEvents] and [THREADSAFE])

Example:

    DIGITAL_INPUT trigger;

    STRING_OUTPUT output$;

    RELEASE trigger

    {

      output$ = "Hello, World!";

    }

In this example, when the DIGITAL_INPUT trigger transitions from high to low, the STRING_OUTPUT output$ will have the string "Hello, World!" put into it.

Version:

X Generation:

SIMPL v1.20.01 and later

SIMPL v1.50.06 and later, DIGITAL_INPUT arrays as \<variable_name\>

2-Series:

SIMPL v2.01.05 and later [Same as X Generation SIMPL v1.50.06] and Local Variables allowed within RELEASE statements.

  [GetLastModifiedArrayIndex]: ../Array_Operations/GetLastModifiedArrayIndex.md
  [StackedEvents]: Stacked_Events.md
  [THREADSAFE]: THREADSAFE.md

Language Constructs & Functions
Events
Release
RELEASE

DIGITAL_INPUT GetLastModifiedArrayIndex RELEASE STRING_OUTPUT StackedEvents THREADSAFE


Stacked Events

# Stacked Events

Stacked Events

Refers to multiple CHANGE, PUSH, or RELEASE functions followed by a single block of code (complex statement).

NOTE:  Only CHANGE, PUSH, or RELEASE functions are used in stacked events. If necessary, refer to the descriptions of each function for details.

A typical event statement may appear as:

    PUSH var1, var2

    {

      // code

    }

SIMPL+ allows event stacking, which allows a block of code to be called from different CHANGE, PUSH, or RELEASE statements. An example is:

    STRING_INPUT A$[100];

    DIGITAL_INPUT IN1, IN2, IN3, IN4;

    ANALOG_INPUT LEVEL;

    ANALOG_INPUT PRESETS[5];

    PUSH IN1

    PUSH IN2

    CHANGE IN3, LEVEL, A$, PRESETS

    RELEASE IN3, IN4

    {

      // code

    }

This allows one piece of code to execute from many different types of event statements.

NOTE: An input signal can be used in more than one event function.  The order of execution is as follows: \
The  order for a PUSH:\
 PUSH statements in the order they appear in the source.\
 CHANGE statements in the order they appear in the source EVENT statement. \
\
The  order for a RELEASE:\
 RELEASE statements in the order they appear in the source.\
 CHANGE statements in the order they appear in the source EVENT statement.

Language Constructs & Functions
Events
Stacked Events

ANALOG_INPUT CHANGE DIGITAL_INPUT EVENT Events PUSH RELEASE STRING_INPUT Stacked


THREADSAFE

# THREADSAFE

Name:

THREADSAFE

Syntax:

    THREADSAFE EVENT { }

    THREADSAFE PUSH \<variable_name\> { }

    THREADSAFE RELEASE \<variable_name\> { }

    THREADSAFE CHANGE \<variable_name\> { }

    THREADSAFE SOCKETCONNECT \<variable_name\> { }

    THREADSAFE SOCKETDISCONNECT \<variable_name\> { }

    THREADSAFE SOCKETRECEIVE \<variable_name\> { }

    THREADSAFE SOCKETSTATUS \<variable_name\> { }

Description:

When using the THREADSAFE keyword before an event (such as PUSH, RELEASE, CHANGE) the event is prevented from retriggering, until the entire code block in the event has executed.

Events prevented from triggering WILL be dropped.

Please be aware, that the value of the digital (in case of PUSH and RELEASE) or Analog/Serial (in case of CHANGE) can still change while the THREADSAFE event is running. The THREADSAFE keyword will eliminate the need for adding a programmatic Semaphore to the body of the event.

NOTE:  Events prevented from triggering WILL be dropped

Example:

DIGITAL_INPUT DigInp;

THREADSAFE PUSH DigInp

{

      // code

}

NOTE:  The above example is equivalent to this:

DIGITAL_INPUT DigInp;

INTEGER semaphore;

FUNCTION Main

{

   semaphore = false;

}

PUSH DigInp

{

   If( semaphore = false )

   {

      semaphore = true;

      // code

      semaphore = false;

   }

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series:  v3.02.00 or later

Language Constructs & Functions
Events
THREADSAFE

CHANGE DIGITAL_INPUT EVENT FUNCTION INTEGER If PUSH RELEASE Serial THREADSAFE


Example 1: Hello, World!

# Example 1: Hello, World!

    // A digital input from the SIMPL program DIGITAL_INPUT TRIG;

    // Upon the digital signal TRIG going high or low, the Hello,

    // World! message is printed.

    CHANGE TRIG

    {

      PRINT("Hello, World!\n");

    }

    // Main is only called once when the system starts up or is reset.

    FUNCTION MAIN()

    {

      PRINT("Main Starts!\n");

    }

Language Constructs & Functions
Example Programs
Example 1   Hello, World!
Example 1: Hello, World!

CHANGE DIGITAL_INPUT Example FUNCTION Hello MAIN PRINT World


# Example 2: 8-Level switch on a Pesa switcher

    #SYMBOL_NAME "Pesa Switcher - 8 Levels"

    #HINT "Creates Pesa CPU-Link H command for Switching"

    /\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

      DIGITAL, ANALOG and SERIAL INPUTS and OUTPUTS

    \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*/

    // Digital trigger from the SIMPL program - this sends the command

    // string out.

    DIGITAL_INPUT TRIG;

    // Analogs for the output and 8 levels of the switcher from the

    // SIMPL program.

    ANALOG_INPUT

    OUTPUT,LEVEL1,LEVEL2,LEVEL3,LEVEL4,LEVEL5,LEVEL6,LEVEL7,LEVEL8;

    // The output string that is to be sent from the SIMPL+ program to

    // the SIMPL program to the switcher.

    STRING_OUTPUT COMMAND$;

    /\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

      Global Variables

      (Uncomment and declare global variables as needed)

    \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*/

    INTEGER I, COUNT, CKSLOW, CKSHI;

    STRING PESABUF[30];

    /\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

      Event Handlers

      (Uncomment and declare additional event handlers as needed)

    \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*/

    PUSH TRIG

    {

      // Format command which stores the switcher command in a

      // temporary buffer. A Command looks like H{out}{l1}{l2}...{l8}

      // {2 byte checksum}{CR}{LF} where {out} and {l1}..{l8} are 3

      // digit ASCII bytes with leading 0s. An example is

      // H001001002003004005006007008{2 bytes checksum}{CR}{LF}

      // makestring(PESABUF,"H%03d%03d%03d%03d%03d%03d%03d%03d%03d",

      // OUTPUT, LEVEL1, LEVEL2, LEVEL3, LEVEL4, LEVEL5, LEVEL6,

      // LEVEL7, LEVEL8);

        COUNT=0;  // Checksum count initialized to 0.

        // Add each byte in the string to the running count.

        for(i=1 to len(pesabuf))

            COUNT = COUNT + BYTE(PESABUF, I);

    // The checksum is computed by taking the COUNT and throwing

        // away all but the lower byte. The upper nibble + '0' is the

        // high order checksum byte, the lower nibble + '0' is the low

        // order checksum byte.

        // Compute the low byte of the checksum.

        CKSLOW = (COUNT & 0x0F) + '0';

        // Compute the high byte of the checksum.

        CKSHI = ((COUNT & 0xF0) \>\> 4) + '0';

        // Send the checksum command to the COMMAND$ that gets routed

        // to the switcher via the SIMPL program.

        makestring(COMMAND$, "%s%s%s", PESABUF, CHR(CKSLOW),

        CHR(CKSHI));

    }

Example 2   8-Level switch on a Pesa switcher

ANALOG_INPUT BYTE CHR DIGITAL_INPUT Example HINT Handlers INTEGER Level PUSH Pesa STRING STRING_OUTPUT SYMBOL_NAME Variables switch switcher


# Example 3: Computing the Number of Days in a Month (Using Functions)

    #SYMBOL_NAME "Compute Number of Days in a Month"

    #ANALOG_INPUT MONTH;

    #ANALOG_OUTPUT DAYS;

    INTEGER_FUNCTION ComputeDaysInMonth(INTEGER Month)

    {

      // Note that this computation does NOT take into account leap

      // year!

      INTEGER Days;

      SWITCH (Month)

      {

        CASE( 2): Days = 28; // February

        CASE( 4): Days = 30; // April

        CASE( 6): Days = 30; // June

        CASE( 9): Days = 30; // September

        CASE(11): Days = 30; // November

        Default:  Days = 31;  // All others

      }

      Return(Days);

    }

    CHANGE MONTH

    {

      DAYS = ComputeDaysInMonth(MONTH);

    }

Example 3   Computing The Number of Days In a Month (Using Functions)

ANALOG_INPUT ANALOG_OUTPUT CASE CHANGE ComputeDaysInMonth Computing Days Example Functions INTEGER INTEGER_FUNCTION Month Number Return SWITCH SYMBOL_NAME Using the


# Example 4: Computing the Number of Days in a Month (Using Function Libraries)

The following code would be saved as, in this example, "My Function Library.USL".

    INTEGER_FUNCTION ComputeDaysInMonth(INTEGER CurrentMonth)

    {

      // Note that this computation does NOT take into account leap

      // year!

      INTEGER NumDays;

     SWITCH(CurrentMonth)

      {

        CASE( 2): NumDays = 28; // February

        CASE( 4): NumDays = 30; // April

        CASE( 6): NumDays = 30; // June

        CASE( 9): NumDays = 30; // September

        CASE(11): NumDays = 30; // November

        Default:  NumDays = 31;  // All others

      }

      Return(NumDays);

    }

The following code can be saved as any filename:

    #SYMBOL_NAME "Compute Number of Days in a Month"

    #USER_LIBRARY "My Function Library"

    ANALOG_INPUT CURRENTMONTH;

    ANALOG_OUTPUT NUMDAYS;

    CHANGE CURRENTMONTH

    {

      NUMDAYS = ComputeDaysInMonth(CURRENTMONTH);

    }

Example 4   Computing The Number of Days In a Month (Using Function Libraries)

ANALOG_INPUT ANALOG_OUTPUT CASE CHANGE ComputeDaysInMonth Computing Days Example Function INTEGER INTEGER_FUNCTION Libraries Month Number Return SWITCH SYMBOL_NAME Using the


Exception Return Error Codes

# Exception Return Error Codes

|                              |       |
|------------------------------|-------|
| CODE                         | VALUE |
| SPLUS_EXCEPTION_UNKNOWN      | -4000 |
| SPLUS_EXCEPTION_OUT_OF_RANGE | -4001 |

Language Constructs & Functions
Exception Handling
Exception Handling Error Codes
Exception Return Error Codes


GetExceptionCode

# GetExceptionCode

Name:

GetExceptionCode

Syntax:

    GetExceptionCode

Description:

Exceptions caught within TRY-CATCH blocks can also be evaluated using the GetExceptionCode function.   The code will either be [SPLUS_EXCEPTION_OUT_OF_RANGE] or [SPLUS_EXCEPTION_UNKNOWN][SPLUS_EXCEPTION_OUT_OF_RANGE].

Example:

Function MyFunc( INTEGER index )

{

   INTEGER intArr[10];

   TRY

   {

      intArr[index] = 1;

      Print( "array index set" );

   }

   CATCH

   {

      Switch( GetExceptionCode() )

      {

         case (SPLUS_EXCEPTION_OUT_OF_RANGE):

         {

         }

         case (SPLUS_EXCEPTION_UNKNOWN):

         {

         }

      }

   }

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [SPLUS_EXCEPTION_OUT_OF_RANGE]: Exception_Handling_Error_Codes.md

Language Constructs & Functions
Exception Handling
GetExceptionCode

GetExceptionCode INTEGER MyFunc Print SPLUS_EXCEPTION_OUT_OF_RANGE Switch


GetExceptionMessage

# GetExceptionMessage

Name:

GetExceptionMessage

Syntax:

    GetExceptionMessage

Description:

Exceptions caught within TRY-CATCH blocks can also be evaluated using the GetExceptionMessage function.  The message will contain a description of the error thrown.

Example:

 Function MyFunc( INTEGER index )

{

INTEGER intArr[10];

TRY

{

intArr[index] = 1;

Print( “array index set” );

}

CATCH

{

Print( “Exception thrown: %s”, GetExceptionMessage() }

}

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

Language Constructs & Functions
Exception Handling
GetExceptionMessage

GetExceptionMessage INTEGER MyFunc Print


TRY-CATCH

# TRY-CATCH

Name:

TRY-CATCH

Syntax:

    TRY { \<statements\> } CATCH { statements }

Description:

TRY-CATCH blocks catch and handle exceptions generated by working code.  Exceptions can be caught and handled in the CATCH portion of the block.  The exception can also be evaluated using either the [GetExceptionMessage] or [GetExceptionCode] function.

Example:

 Function MyFunc( INTEGER index )

 {

INTEGER intArr[10];

TRY

{

intArr[index] = 1;

Print( “array index set” );

}

CATCH

{

Print( “array index out of bounds: %d”, index );

}

}

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [GetExceptionMessage]: GetExceptionMessage.md
  [GetExceptionCode]: GetExceptionCode.md

Language Constructs & Functions
Exception Handling
TRY-CATCH

CATCH GetExceptionCode GetExceptionMessage INTEGER MyFunc Print TRY


Expressions & Statements

# Expressions & Statements

An expression consists of operators and operands.

i.e.

    5 \* 6

or

    (VAL1 + 5) / 30

or

     (26 + BYTE(THESTRING$,1)) MOD Z = 25

Statements consist of function calls, expressions, assignments, or other instructions. There are two types of statements, Simple and Complex.

A simple statement ends with a semicolon (;). Examples of simple statements are:

    X = Z/10;                   // Simple assignment statement using

                                // operators.

    PRINT("Hello, World!\n");   // Simple statement using a function

                                // call.

    CHECKSUM = ATOI(Z$) + 5;    // Simple assignment statement using

                                // a function call and operators.

A complex statement is a collection of simple statements that start with '{' and end with '}'. An example would be:

    { // Start of a complex statement

      X = Z/10;                 // Simple assignment statement

                                // using operators.

      PRINT("Hello, World!\n"); // Simple statement using a

                                // function call.

      CHECKSUM = ATOI(Z$) + 5;  // Simple assignment statement

                                // using a function call and

                                // operators.

    } // End of a Complex statement

Language Constructs & Functions
Expressions & Statements


CheckForDisk

# CheckForDisk

Name:

CheckForDisk

Syntax:

    INTEGER CheckForDisk()

Description:

Tests whether or not a compact flash card is currently installed in the control system.

Parameters:

None.

Return Value:

Returns 1 if a compact flash card is currently installed in the control system.

see also [WaitForNewDisk][]()

Example:

(see [File Functions Overview])

    StartFileOperations(); // all file operations must first identify themselves with the operating system

    IF ( CheckForDisk () = 1 )

      PRINT ( "compact flash card found" );

    EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [WaitForNewDisk]: WaitForNewDisk.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
CheckForDisk

CheckForDisk EndFileOperations File Functions IF INTEGER Overview PRINT StartFileOperations WaitForNewDisk


CheckForNVRAMDisk

# CheckForNVRAMDisk

Name:

CheckForNVRAMDisk

Syntax:

INTEGER CheckForNVRAMDisk()

Description:

Tests whether or not an NVRam Disk is currently installed in the control system.

Parameters:

None.

Return Value:

Returns 1 if an NVRam Disk is currently installed in the control system.

Example:

    (refer to [File Functions Overview])

    IF ( CheckForNVRAMDisk() = 1 )

        PRINT ( "NVRAM Disk found" );

Version:

X Generation:  Not Supported

2-Series:  SIMPL v2.04.11 and later

  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
CheckForNVRAMDisk

CheckForNVRAMDisk File Functions IF INTEGER Overview PRINT


EndFileOperations

# EndFileOperations

Name:

EndFileOperations

Syntax:

    SIGNED_INTEGER EndFileOperations()

Description:

Signifies to the operating system that the current thread has completed its file operations.

[StartFileOperations] is required prior to any operation accessing a file, including all functions in  [FileOpen].

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])

   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

  [StartFileOperations]: StartFileOperations.md
  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
EndOfFileOperations
EndFileOperations

EndFileOperations File FileOpen Functions IF Overview PRINT PUSH SIGNED_INTEGER StartFileOperations

StartFileOperations
FileOpen
File Functions Overview


FileBOF

# FileBOF

Name:

FileBOF

Syntax:

    SIGNED_INTEGER FileBOF (INTEGER handle)

Description:

Tests whether or not the current file pointer is at the beginning of the file.

Parameters:

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

Return Value:

Returns 1 if beginning of file or 0 if not end of file. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

    SIGNED_INTEGER  nFileHandle;

StartFileOperations();

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

    IF (nFileHandle \< 0)

    {

      PRINT("Error Opening File MyFile\n");

      return;

    }

    IF ( FileBOF ( nFileHandle )  = 1 )

      PRINT ( "Beginning of file reached\n" );

    IF ( FileClose ( nFileHandle ) \<\> 0 )

      PRINT ( "Error closing file" );

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileBOF

EndFileOperations File FileBOF FileClose FileOpen Functions IF INTEGER Overview PRINT SIGNED_INTEGER StartFileOperations code error

FileOpen
error code
File Functions Overview


FileClose

# FileClose

Name:

FileClose

Syntax:

    SIGNED_INTEGER FileClose (INTEGER handle)

Description:

Closes a file opened previously by [FileOpen]. You MUST close a file that was opened, you won't be able to open it again, or eventually the control system may hang or reboot. A reboot clears all open files. Files must be opened and closed during a single thread of operation. Refer to [StartFileOperation]s.

Parameters:

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

Return Value:

Returns 0 if successful. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

    SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

    IF (nFileHandle \< 0)

    {

      PRINT("Error Opening File MyFile\n");

      return;

    }

    IF (nFileHandle \>= 0)

    {

      IF ( FileClose ( nFileHandle ) \<\> 0 )

        PRINT ( "Error closing file\n" );

    }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [StartFileOperation]: StartFileOperations.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileClose

EndFileOperations File FileClose FileOpen Functions IF INTEGER Overview PRINT SIGNED_INTEGER StartFileOperation StartFileOperations code error

FileOpen
StartFileOperation
error code
File Functions Overview


FileDelete

# FileDelete

Name:

FileDelete

Syntax:

    SIGNED_INTEGER FileDelete (STRING filename)

Description:

Deletes the specified file from the file system.

[FileOpen] and [FindFirst] should be used in conjunction with FileDelete when necessary.

NOTE: Refer to the [File Functions Overview] topic statement on [Shared File Functions] for more information.

Parameters:

FILENAME specifies the name of the file to delete. Can contain wildcards (\*) if a full path is not given.

Return Value:

Returns 0 if successful. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

StartFileOperations();

IF ( FileDelete ( "\\CF0\\MyFile" ) \<\> 0 )

      PRINT ( "Error deleting file\n" );

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [FindFirst]: File_First.md
  [File Functions Overview]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [error code]: File_Function_Return_Error_Codes.md

Language Constructs & Functions
File Functions
FileDelete

EndFileOperations File FileDelete FileOpen FindFirst Functions IF Overview PRINT SIGNED_INTEGER STRING StartFileOperations code error

FileOpen
FindFirst
File Functions Overview
error code


FileDeleteShared

# FileDeleteShared

Name:

FileDeleteShared

Syntax:

    SIGNED_INTEGER FileDeleteShared (STRING filename)

Description:

Deletes the specified shared file from the file system.

[FindFirstShared] and [FileOpenShared] should be used in conjunction with FileDeleteShared when necessary.

NOTE: Refer to the [File Functions Overview] topic statement on [Shared File Functions] for more information.

Parameters:

FILENAME specifies the name of the file to delete. Can contain wildcards (\*) if a full path is not given.

Return Value:

Returns 0 if successful. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

StartFileOperations();

IF ( FileDeleteShared ( "\\CF0\\MyFile" ) \<\> 0 )

      PRINT ( "Error deleting file\n" );

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [FindFirstShared]: FindFirstShared.md
  [FileOpenShared]: FileOpenShared.md
  [File Functions Overview]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [error code]: File_Function_Return_Error_Codes.md

Language Constructs & Functions
File Functions
FileDeleteShared

EndFileOperations File FileDeleteShared FileOpenShared FindFirstShared Functions IF Overview PRINT SIGNED_INTEGER STRING StartFileOperations code error

FindFirstShared
FileOpenShared
File Functions Overview
error code


FileEOF

# FileEOF

Name:

FileEOF

Syntax:

    SIGNED_INTEGER FileEOF (INTEGER handle)

Description:

Tests whether or not the current file pointer is at the end of the file.

Parameters:

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

Return Value:

Returns 1 if end of file or 0 if not end of file. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

    SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

    IF (nFileHandle \< 0)

    {

      PRINT("Error Opening File MyFile\n");

      return;

    }

    IF ( FileEOF ( nFileHandle ) = 1 )

      PRINT ( "End of file reached\n" );

    IF ( FileClose ( nFileHandle ) \<\> 0 )

      PRINT ( "Error closing file\n" );

    EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileEOF

EndFileOperations File FileClose FileEOF FileOpen Functions IF INTEGER Overview PRINT SIGNED_INTEGER StartFileOperations code error


FileLength

# FileLength

Name:

FileLength

Syntax:

    LONG_INTEGER FileLength (INTEGER handle)

Description:

Returns the length of a file.

Parameters:

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

Return Value:

Number of bytes if successful. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

 SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

    IF (nFileHandle \< 0)

    {

      PRINT("Error Opening File MyFile\n");

      return;

    }

 IF ( nFileHandle \> 0 )

    PRINT ( "Length of file = %d\n",

            FileLength ( nFileHandle ) );

 IF ( FileClose ( nFileHandle ) \<\> 0 )

    PRINT ( "Error closing file\n" );

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileLength

EndFileOperations File FileClose FileLength FileOpen Functions IF INTEGER LONG_INTEGER Overview PRINT SIGNED_INTEGER StartFileOperations code error


FileOpen (Part 1)

# FileOpen

Name:

FileOpen

Syntax:

    SIGNED_INTEGER FileOpen (STRING filename, INTEGER flags)

Description:

*3-Series and 4-Series*

Opens a file in the specified folder, prepending the Program ID Tag to the filename. For example, if you have a program called "HVAC" and want to open a file called "myFile.dat" in the directory, \NVRAM, the file “\NVRAM\HVAC\myFile.dat” will be opened.

**Virtual Control**

Opens a file in the specified folder. On Virtual Control, we will \*not\* prepend the Program ID Tag to the filename. For example, if you have a room called "HVAC" and want to open a file called "myFile.dat" in the directory, \NVRAM, the file “\NVRAM\\myFile.dat” will be opened for that specific room.

Please see [File Functions Overview] for additional information.\
\

[FindFirst] and [FileDelete] should be used in conjunction with FileOpen when necessary.

NOTE:  The function, [FileOpenShared] will not prepend the Program ID Tag to the filename.

NOTE: Refer to the [File Functions Overview][1] topic statement on [Shared File Functions] for more information.

Parameters:

FILENAME specifies the full path name or relative path name (link) of the file to open/create.

FLAGS – File Open Flags. Can be combined using the Bitwise OR operator (|)

NOTE:  One of the following flags must be specified: _O_RDONLY, _O_WRONLY, or _O_RDWR.

NOTE: When writing to the NVRAM disk, only one file can be open at one time.  Subsequent requests to write a file will block for a period of time (currently 5 seconds) until the initial write completes.  If the request times out, an error code of FILE_SHARE will be returned.  It is then up to the programmer to retry or signify an error condition.

Open File Flags

|  |  |
|----|----|
| KEYWORD | FUNCTION |
| _O_APPEND | Writes done at the end of file.  Mutually exclusive with _O_TRUNC. |
| _O_CREAT | Creates file.  If _O_APPEND is specified, the file will be created only if it doesn't already exist. |
| _O_EXCL | Open succeeds only if file doesn't already exist. |
| _O_TRUNC | Truncates file.  Mutually exclusive with _O_APPEND. |
| _O_TEXT | Indicates the file is text. |
| _O_BINARY | Indicates the file is binary (basically raw data). |
| _O_RDONLY | Open file for reading only |
| _O_RDWR | Open file for both reading and writing |
| _O_WRONLY | Open file for writing only |

Return Value:

File handle if successful ( \>= 0). Otherwise, file [error code] is returned.

NOTE:  [FileClose][]() must be called before the executing thread is terminated.  Failure to do so will result in the file being left open and locked by the control system.  Should this happen, the file will not be able to be opened again until the control system is rebooted.

Examples:

(see [File Functions Overview][1])

1\. Open a file for read only:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

   IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

2\. Open an existing file to log data to the end:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

Language Constructs & Functions
File Functions
FileOpen
FileOpen

EndFileOperations FUNCTION FileOpen IF INTEGER PRINT Part SIGNED_INTEGER STRING StartFileOperations


FileOpen (Part 2)

3\. If a file exists, truncate it and get rid of previous contents. If it doesn't exist, create it.

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

     }

EndFileOperations();

4\. Continue adding to the end of an existing log file, or create it if it does not already exist.

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [File Functions Overview]: File_Functions_Overview.md
  [FindFirst]: File_First.md
  [FileDelete]: FileDelete.md
  [FileOpenShared]: FileOpenShared.md
  [1]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [error code]: File_Function_Return_Error_Codes.md
  [FileClose]: FileClose.md

EndFileOperations File FileClose FileDelete FileOpen FileOpenShared FindFirst Functions IF Overview PRINT Part SIGNED_INTEGER StartFileOperations code error

File Functions Overview
FindFirst
FileDelete
FileOpenShared
1
error code
FileClose

Open a file for read only:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

   IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

2\. Open an existing file to log data to the end:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();


FileOpenShared (Part 1)

# FileOpenShared

Name:

FileOpenShared

Syntax:

    SIGNED_INTEGER FileOpenShared (STRING filename, INTEGER flags)

Description:

*3-Series and 4-Series\*

*Opens a file in the specified folder.  Unlike the function, [FileOpen], this function will not prepend the Program ID Tag with the filename.\*

**Virtual Control**

Opens a file in the specified folder. On Virtual Control, we will not prepend the Program ID Tag to the filename. For example, if you have a room called "HVAC" and want to open a file called "myFile.dat" in the directory, \NVRAM, the file “\NVRAM\\myFile.dat” will be opened for that specific room.

Please see [File Functions Overview] for additional information.

[FindFirstShared] and [FileDeleteShared] should be used in conjunction with FileOpenShared when necessary.

NOTE: Refer to the [File Functions Overview][1] topic statement on [Shared File Functions] for more information.

NOTE:  The function, [FileOpen][2], will prepend the Program ID Tag to the filename

Parameters:

FILENAME specifies the full path name or relative path name (link) of the file to open/create.

FLAGS – File Open Flags. Can be combined using the Bitwise OR operator (|)

NOTE:  One of the following flags must be specified: _O_RDONLY, _O_WRONLY, or _O_RDWR.

NOTE: When writing to the NVRAM disk, only one file can be open at one time.  Subsequent requests to write a file will block for a period of time (currently 5 seconds) until the initial write completes.  If the request times out, an error code of FILE_SHARE will be returned.  It is then up to the programmer to retry or signify an error condition.

Open File Flags

|  |  |
|----|----|
| KEYWORD | FUNCTION |
| _O_APPEND | Writes done at the end of file.  Mutually exclusive with _O_TRUNC. |
| _O_CREAT | Creates file.  If _O_APPEND is specified, the file will be created only if it doesn't already exist. |
| _O_EXCL | Open succeeds only if file doesn't already exist. |
| _O_TRUNC | Truncates file.  Mutually exclusive with _O_APPEND. |
| _O_TEXT | Indicates the file is text. |
| _O_BINARY | Indicates the file is binary (basically raw data). |
| _O_RDONLY | Open file for reading only |
| _O_RDWR | Open file for both reading and writing |
| _O_WRONLY | Open file for writing only |

Return Value:

File handle if successful ( \>= 0). Otherwise, file [error code] is returned.

NOTE:  [FileClose][]() must be called before the executing thread is terminated.  Failure to do so will result in the file being left open and locked by the control system.  Should this happen, the file will not be able to be opened again until the control system is rebooted.

Examples:

(see [File Functions Overview][1])

1\. Open a file for read only:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

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

   IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

2\. Open an existing file to log data to the end:

SIGNED_INTEGER nFileHandle;

StartFileOperations();

nFileHandle = FileOpenShared ("\\CF0\\MyFile", _O_WRONLY | _O_APPEND) ;

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

3\. If a file exists, truncate it and get rid of previous contents. If it doesn't exist, create it.

SIGNED_INTEGER nFileHandle;

Language Constructs & Functions
File Functions
FileOpenShared
FileOpenShared

EndFileOperations FUNCTION FileOpenShared IF INTEGER PRINT Part SIGNED_INTEGER STRING StartFileOperations


FileOpenShared (Part 2)

StartFileOperations();

nFileHandle = FileOpenShared ("\\CF0\\MyFile", _O_WRONLY | _O_CREAT | _O_TRUNC) ;

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

     }

EndFileOperations();

4\. Continue adding to the end of an existing log file, or create it if it does not already exist.

SIGNED_INTEGER nFileHandle;

StartFileOperations();

nFileHandle = FileOpenShared ("\\CF0\\MyFile", _O_WRONLY | _O_APPEND | _O_CREAT);

IF (nFileHandle \< 0)

   {

   PRINT("Error Opening File MyFile\n");

      }

EndFileOperations();

Version:

X Generation:  Not Supported

2-Series:  Not Supported

3-Series: v \<\> and above

  [FileOpen]: FileOpen.md
  [File Functions Overview]: File_Functions_Overview.md
  [FindFirstShared]: FindFirstShared.md
  [FileDeleteShared]: FileDeleteShared.md
  [1]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [2]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [FileClose]: FileClose.md

EndFileOperations File FileClose FileDeleteShared FileOpen FileOpenShared FindFirstShared Functions IF Overview PRINT Part SIGNED_INTEGER StartFileOperations code error

FileOpen
File Functions Overview
FindFirstShared
FileDeleteShared
1
2
error code
FileClose

If it doesn't exist, create it. SIGNED_INTEGER nFileHandle;


FileRead

# FileRead

Name:

FileRead

Syntax:

   SIGNED_INTEGER FileRead (INTEGER handle, STRING buffer,

INTEGER count )

Description:

Reads data from a file as a series of bytes into a buffer, starting at the current file position. 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: [ReadInteger], [ReadString], [ReadStructure], [ReadSignedInteger], [ReadLongInteger], [ReadSignedLongInteger], [ReadIntegerArray], [ReadSignedIntegerArray], [ReadLongIntegerArray], [ReadSignedLongIntegerArray], [ReadStringArray].

To avoid an error being generated by the console, use [FileEOF()] to test for end of file prior to reading.

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

To read a single byte, use this function.

Parameters:

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

BUFFER is the destination variable for bytes that are read.

COUNT specifies the number of bytes to read.

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;

    STRING sBuf[4096];

StartFileOperations();

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

    IF (nFileHandle \>= 0)

    {

      WHILE (FileRead(nFileHandle, sBuf, 4096) \> 0)

        PRINT ( "Read from file: %s\n", sBuf );

      IF ( FileClose ( nFileHandle ) \<\> 0 )

        PRINT ( "Error closing file\n" );

    }

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
  [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
  [ReadStringArray]: ReadStringArray.md
  [FileEOF()]: FileEOF.md
  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileRead

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

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


FileSeek

# FileSeek

Name:

FileSeek

Syntax:

    SIGNED_LONG_INTEGER FileSeek (INTEGER handle, SIGNED_LONG_INTEGER offset,

                      INTEGER origin )

Description:

Positions the current file pointer.

Parameters:

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

OFFSET specifies the number of bytes to move relative to the origin.

ORIGIN is one of the file seek flags in the following table.

File Seek Flags

|          |                                             |
|----------|---------------------------------------------|
| KEYWORD  | FUNCTION                                    |
| SEEK_SET | Start seeking from beginning of file        |
| SEEK_CUR | Start seeking from current position in file |
| SEEK_END | Start seeking from end of file              |

Return Value:

Number of bytes offset from the beginning of file. Otherwise, file [error code] is returned.

Example:

(see [File Functions Overview])

    SIGNED_INTEGER  nFileHandle;

StartFileOperations();

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

    IF (nFileHandle \>= 0)

    {

      IF (FileSeek( nFileHandle, 0, SEEK_SET)) \< 0 )

        PRINT ( "Error seeking file\n" );

      IF ( FileClose ( nFileHandle ) \<\> 0 )

        PRINT ( "Error closing file\n" );

    }

EndFileOperations();

Other Examples:

1\. Go to beginning of file\
FileSeek (nFileHandle,0,SEEK_SET)

2\. Go to end of file\
FileSeek (nFileHandle,0,SEEK_END)

3\. Get current file position\
CurrentBytePosition= FileSeek(nFileHandle,0,SEEK_CUR)

Version:

X Generation:  Not Supported

2-Series:  SIMPL Version 2.02.10 and later

  [FileOpen]: FileOpen.md
  [error code]: File_Function_Return_Error_Codes.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileSeek

EndFileOperations FUNCTION File FileClose FileOpen FileSeek Functions IF INTEGER Overview PRINT SIGNED_INTEGER SIGNED_LONG_INTEGER StartFileOperations code error


FileWrite

# FileWrite

Name:

FileWrite

Syntax:

 SIGNED_INTEGER FileWrite (INTEGER handle, STRING buffer,

INTEGER count )

Description:

Writes data to a file as a series of bytes from a buffer, starting at the current file position. 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: [WriteInteger], [WriteString], [WriteStructure], [WriteSignedInteger], [WriteLongInteger], [WriteSignedLongInteger], [WriteIntegerArray,] [WriteSignedIntegerArray], [WriteLongIntegerArr]ay, [WriteSignedLongIntegerArray,] [WriteStringArray.]

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

Parameters:

HANDLE specifies the file handle of the previously opened file (from FileOpen).

BUFFER is the variable containing the bytes to be written.

COUNT specifies the number of bytes to 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;

    STRING sBuf[4096];

StartFileOperations();

    sBuf = "Hello World!";

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

    IF (nFileHandle \>= 0)

    {

      if( FileWrite(nFileHandle, sBuf, 4096) \> 0 )

        PRINT ( "Written to file: %s\n", sBuf );

      IF ( FileClose ( nFileHandle ) \<\> 0 )

        PRINT ( "Error closing file\n" );

    }

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
  [WriteInteger]: WriteInteger.md
  [WriteString]: WriteString.md
  [WriteStructure]: WriteStructure.md
  [WriteSignedInteger]: WriteSignedInteger.md
  [WriteLongInteger]: WriteLongInteger.md
  [WriteSignedLongInteger]: WriteSignedLongInteger.md
  [WriteIntegerArray,]: WriteIntegerArray.md
  [WriteSignedIntegerArray]: WriteSignedIntegerArray.md
  [WriteLongIntegerArr]: WriteLongIntegerArray.md
  [WriteSignedLongIntegerArray,]: WriteSignedLongIntegerArray.md
  [WriteStringArray.]: WriteStringArray.md
  [File Functions Overview]: File_Functions_Overview.md

Language Constructs & Functions
File Functions
FileWrite

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

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


FindFirst

# FindFirst

Name:

FindFirst

Syntax:

    SIGNED_INTEGER FindFirst(STRING filespec, FILE_INFO info)

Description:

This command searches a directory for file(s) matching the given file specification. Always followed with a [FindClose]. Requires [StartFileOperations()].

[FileOpen] and [FileDelete] should be used in conjunction with FindFirst when necessary.

NOTE: Refer to the [File Functions Overview] topic statement on [Shared File Functions] for more information.

Parameters:

FILESPEC specifies the filename to look for. It can be a full path name or a [relative path name] with wildcards ( the ‘\*’ character).

INFO – FILE_INFO structure containing the information about a found file:

File Attribute Bit Flags (May be checked with bitwise & character)

|         |                                 |
|---------|---------------------------------|
| KEYWORD | ATTRIBUTE                       |
| ARDONLY | File is marked read only        |
| AHIDDEN | File is hidden                  |
| ASYSTEM | File is marked as a system file |
| AVOLUME | File is a volume label          |
| ADIRENT | File is a directory             |
| ARCHIVE | File is marked as archived      |

Return Value:

Returns 0 if a file is found matching the specification and –1 if an error occurred.

Example:

(see [File Functions Overview])

    FILE_INFO FileInfo;

    SIGNED_INTEGER Found;

StartFileOperations();

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

    WHILE (Found = 0)

    {

      IF ((FileInfo.iAttributes & ADIRENT)\<\>0)

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

else

 PRINT ("%s is a 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

  [FindClose]: FindClose.md
  [StartFileOperations()]: StartFileOperations.md
  [FileOpen]: FileOpen.md
  [FileDelete]: FileDelete.md
  [File Functions Overview]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [relative path name]: ../../General_Information/Relative_Path_Names_for_Files.md

Language Constructs & Functions
File Functions
File First
FindFirst

EndFileOperations File FileDelete FileOpen FindClose FindFirst FindNext Flags Functions IF Overview PRINT SIGNED_INTEGER STRING StartFileOperations WHILE name path relative

FindClose
StartFileOperations()
FileOpen
FileDelete
File Functions Overview
relative path name


File Function Return Error Codes

# File Function Return Error Codes

|  |  |  |
|----|----|----|
| KEYWORD | VALUE | FUNCTION |
| FILE_BAD_USER | -3000 | Calling task is not a file user. Use StartFileOperations() first. |
| FILE_NO_DISK | -3004 | Disk is removed. |
| FILE_LONGPATH | -3017 | Path or directory name too long. |
| FILE_INVNAME | -3018 | Path or filename includes invalid character. |
| FILE_PEMFILE | -3019 | No file descriptors available (Too many files open). |
| FILE_BADFILE | -3020 | Invalid file descriptor. |
| FILE_ACCES | -3021 | Attempt to open a read-only file or special (directory). Also the error code you get when trying to make a directory on a volume that does not support it (i.e. NVRAM or internal flash). |
| FILE_NOSPC | -3022 | No space to create file in this disk. |
| FILE_SHARE | -3023 | The access conflicts from multiple tasks to a specific file. Can also occur when attempting to write multiple files to the NVRAM disk at the same time. |
| FILE_NOFILE | -3024 | File not found. |
| FILE_EXIST | -3025 | Exclusive access requested, but file already exists. |
| FILE_NVALFP | -3026 | Seek to negative file pointer. |
| FILE_MAXFILE_SIZE | -3027 | Over the maximum file size. |
| FILE_NOEMPTY | -3028 | Directory is not empty. |
| FILE_INVPARM | -3029 | Invalid Flag/Mode is specified. |
| FILE_INVPARCMB | -3030 | Invalid Flag/Mode combination. |
| FILE_NO_MEMORY | -3031 | Can't allocate internal buffer. |
| FILE_NO_BLOCK | -3032 | No block buffer available. |
| FILE_NO_FINODE | -3033 | No FINODE buffer available. |
| FILE_NO_DROBJ | -3034 | No DROBJ buffer available. |
| FILE_IO_ERROR | -3035 | Driver I/O function routine returned. |
| FILE_INTERNAL | -3036 | Internal error. |
| FILE_UNAUTH    | -4000 | Unauthorized access. |
| FILE_TYPEUNSUPP    | -4001 | Type not supported. |
| FILE_INVENC | -4002 | Invalid encoding found when reading a string. |
| FILE_BINERR | -4003 | Cannot write binary data to file opened with TEXT flag. |
| FILE_CORRUPT | -4004 | Header on the file is invalid - file cannot be opened. |
| FILE_NEWER_VERSION | -4005 | The file version number is greater than what is supported. Compile Simpl+. |

Language Constructs & Functions
File Functions
File Function Return Error Codes

Codes Error FUNCTION File Function Return StartFileOperations


File Functions Overview (Part 1)

# File Functions Overview

File Functions perform file handle access from SIMPL+. Because of the overhead involved with maintaining current directory and file positions, there are restrictions on file I/O. Each SIMPL+ thread (main loop or event handler) that requires file operations must first identify itself with the operating system. This is done with the function, [StartFileOperations].  Before terminating the thread, the function [EndFileOperations] must be called.  Files cannot be opened across threads. In other words, you cannot open a file in one thread (function main say) and then access the file with the returned file handle in another (say an event handler). This is to prevent two events from writing to different parts of a file. This means that you should open, access and then close a file within the same thread.  For example, a program might be structured as follows:

STRING sBuf[1000];

SIGNED_INTEGER nFileHandle;

CHANGE input

{

        SIGNED_INTEGER nNumRead;

        StartFileOperations();

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

        if ( nFileHandle \>= 0 )

        {

nNumRead=FileRead( nFileHandle, sBuf, 500;

Print ("Read Error\n");

FileClose( nFileHandle );

        }

        EndFileOperations();

}

/\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*

Main()

Uncomment and place one-time startup code here

(This code will get called when the system starts up)

\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*/

Function Main()

{

SIGNED_INTEGER nNumWritten;

        StartFileOperations();

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

        if ( nFileHandle \>= 0 )

        {

                sBuf = "Hello World!";

                nNumWritten=FileWrite( nFileHandle, sBuf, 500 );

 if(nNumWritten\<0) Print ("WriteError");

                FileClose( nFileHandle );

        }

        EndFileOperations();

}

Shared File Functions.

There are now shared file functions in SIMPL+. The shared file functions are briefly described in the following paragraphs:

[FileOpenShared] opens a file in the specified folder.  Unlike the function, [FileOpen], this function will not prepend the Program ID Tag with the filename.  FileOpen opens a file in the specified folder, prepending the Program ID Tag to the filename.  For example, if you have a program called "HVAC" and want to open a file called "myFile.dat" in the directory, \NVRAM, the file “\NVRAM\HVAC\myFile.dat” will be opened.

[FindFirst] and [FileDelete] should be used in conjunction with FileOpen.

[FindFirstShared] and [FileDeleteShared] should be used in conjunction with FileOpenShared.

Virtual Control:

By default, Virtual Control installs in/opt/crestron/virtualcontrol/and any rooms that are started have their own separate folder in /opt/crestron/virtualcontrol/RunningPrograms/ROOMID.

Where ROOMID here is the unique ID that is used when the room gets created.

Language Constructs & Functions
File Functions
File Functions Overview
File Functions Overview

CHANGE EndFileOperations File FileClose FileOpen FileRead FileWrite Functions Main Overview Part Print SIGNED_INTEGER STRING StartFileOperations


File Functions Overview (Part 2)

For example, when/User/File.txtis opened on Virtual Control, /opt/crestron/virtualcontrol/RunningPrograms/ROOMID/User/File.txt is actually opened.

On Virtual Control, every program runs in a single “room” and there is no sharing between rooms.

So, for Virtual Control specific, FileOpen() and FileOpenShared() will both go to the exact same folder and won’t prepend Program ID Tag with the filename.

This is different from 3-Series and 4-Series behavior and won’t prepend Program ID Tag with the filename. This is different from 3-Series and 4-Series behavior.

  [StartFileOperations]: StartFileOperations.md
  [EndFileOperations]: EndOfFileOperations.md
  [FileOpenShared]: FileOpenShared.md
  [FileOpen]: FileOpen.md
  [FindFirst]: File_First.md
  [FileDelete]: FileDelete.md
  [FindFirstShared]: FindFirstShared.md
  [FileDeleteShared]: FileDeleteShared.md

EndFileOperations File FileDelete FileDeleteShared FileOpen FileOpenShared FindFirst FindFirstShared Functions Overview Part StartFileOperations

StartFileOperations EndFileOperations FileOpenShared FileOpen FindFirst FileDelete FindFirstShared FileDeleteShared

Virtual Control:

By default, Virtual Control installs in/opt/crestron/virtualcontrol/and any rooms that are started have their own separate folder in /opt/crestron/virtualcontrol/RunningPrograms/ROOMID. Where ROOMID here is the unique ID that is used when the room gets created.


FILE_INFO Structure

# FILE_INFO Structure

Use this structure to retrieve information about a file.

   STRUCTURE FILE_INFO

        {

             STRING Name;            // relative name of the found file

             INTEGER iAttributes;    // attributes for the file

             INTEGER iTime;          // file time in packed form

             INTEGER iDate;          // file date in packed form

             LONG_INTEGER lSize;     // size of the file in bytes

        };

File Attribute Bit Flags (These may be bitwise OR'ed together)

|         |                                 |                            |
|---------|---------------------------------|----------------------------|
| KEYWORD | ATTRIBUTE                       | EQUIVALENT SIMPL+ FUNCTION |
| ARDONLY | File is marked read only        | IsReadOnly                 |
| AHIDDEN | File is hidden                  | IsHidden                   |
| ASYSTEM | File is marked as a system file | IsSystem                   |
| AVOLUME | File is a volume label          | IsVolume                   |
| ADIRENT | File is a directory             | IsDirectory                |
| ARCHIVE | File is marked as an archive    |                            |

NOTE: For an example on how and where to use the FILE_INFO structure, refer to the example code for [FindFirst].

Version:

SIMPL+ Version 3.00.02 or higher (2-series only)

  [FindFirst]: File_First.md

Language Constructs & Functions
File Functions
File INFO Structure
FILE_INFO Structure

FILE_INFO FUNCTION FindFirst Flags INTEGER LONG_INTEGER STRING STRUCTURE Structure


File Time and Date Functions Overview

# File Time and Date Functions Overview

These versions of the Time and Date functions in a given SIMPL+ program are used to retrieve information about the current date and time from the file info structure returned from [FINDFIRST]/[FINDNEXT]. Values can be retrieved as text strings i.e. "January" or integer values. Typically, integer values are used if computations need to be performed (i.e. when the date is the 25th, perform a specific action).

  [FINDFIRST]: File_First.md
  [FINDNEXT]: FindNext.md

Language Constructs & Functions
File Functions
File Time and Date Functions Overview

Date FINDFIRST FINDNEXT File Functions Overview Time and


FindClose

# FindClose

Name:

FindClose

Syntax:

   SIGNED_INTEGER FindClose()

Description:

Signifies to the operating system that the find operation has ended. Always follows a [FindFirst] or [FindNext].

Parameters:

None.

Return Value:

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

Example:

(see [File Functions Overview])

 [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

StartFileOperations();

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

    WHILE (Found = 0)

    {

      PRINT ( "%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.02.10 and later

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

Language Constructs & Functions
File Functions
FindClose

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

FindFirst
FindNext
File Functions Overview
FILE_INFO


FindFirstShared

# FindFirstShared

Name:

FindFirstShared

Syntax:

    SIGNED_INTEGER FindFirstShared(STRING filespec, FILE_INFO info)

Description:

This command searches a directory for file(s) matching the given file specification (first file shared). Always followed with a [FindClose]. Requires [StartFileOperations()].

[FileOpenShared] and [FileDeleteShared] should be used in conjunction with FindFirstShared when necessary.

NOTE: Refer to the [File Functions Overview] topic statement on [Shared File Functions] for more information.

Parameters:

FILESPEC specifies the filename to look for. It can be a full path name or a [relative path name] with wildcards ( the ‘\*’ character).

INFO – FILE_INFO structure containing the information about a found file:

File Attribute Bit Flags (May be checked with bitwise & character)

|         |                                 |
|---------|---------------------------------|
| KEYWORD | ATTRIBUTE                       |
| ARDONLY | File is marked read only        |
| AHIDDEN | File is hidden                  |
| ASYSTEM | File is marked as a system file |
| AVOLUME | File is a volume label          |
| ADIRENT | File is a directory             |
| ARCHIVE | File is marked as archived      |

Return Value:

Returns 0 if a file is found matching the specification and –1 if an error occurred.

Example:

(see [File Functions Overview])

    FILE_INFO FileInfo;

    SIGNED_INTEGER Found;

StartFileOperations();

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

    WHILE (Found = 0)

    {

      IF ((FileInfo.iAttributes & ADIRENT)\<\>0)

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

else

 PRINT ("%s is a 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:  Not Supported

3-Series: v \<\> and above

  [FindClose]: FindClose.md
  [StartFileOperations()]: StartFileOperations.md
  [FileOpenShared]: FileOpenShared.md
  [FileDeleteShared]: FileDeleteShared.md
  [File Functions Overview]: File_Functions_Overview.md
  [Shared File Functions]: javascript:void(0);
  [relative path name]: ../../General_Information/Relative_Path_Names_for_Files.md

Language Constructs & Functions
File Functions
FindFirstShared

EndFileOperations File FileDeleteShared FileOpenShared FindClose FindFirstShared FindNext Flags Functions IF Overview PRINT SIGNED_INTEGER STRING StartFileOperations WHILE name path relative

FindClose
StartFileOperations()
FileOpenShared
FileDeleteShared
File Functions Overview
relative path name


FindNext

# FindNext

Name:

FindNext

Syntax:

    SIGNED_INTEGER FindNext(FILE_INFO info)

Description:

This command continues the current directory for file(s) matching the file specification in the [FindFirst] command.

Parameters:

INFO – structure containing the information about a found file (see [FindFirst] for description). Must be followed by a [FindClose].

Return Value:

Returns 0 if a file is found matching the specification and –1 if an error occurred.

Example:

(see [File Functions Overview])

    [FILE_INFO] FileInfo;

    SIGNED_INTEGER Found;

StartFileOperations();

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

    WHILE (Found = 0)

    {

      PRINT ( "%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.02.10 and later

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

Language Constructs & Functions
File Functions
FindNext

FindFirst
FindClose
File Functions Overview
FILE_INFO


GetCurrentDirectory

# GetCurrentDirectory

Name:

GetCurrentDirectory

Syntax:

    STRING GetCurrentDirectory()

Description:

Returns the complete path name of the current working directory. Refer to [Relative Path Names] for a discussion of setting the current directory. It ends with "\\.

Parameters:

None.

Return Value:

String containing the current directory.  If an error occurs, string length equals 0.

Example:

(see [File Functions Overview])

   PRINT( "The current directory =  %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
GetCurrentDirectory

File Functions GetCurrentDirectory Names Overview PRINT Path Relative STRING

Relative Path Names
File Functions Overview