SMin

# SMin

Name:

SMin

Syntax:

    INTEGER SMin(INTEGER VAL1, INTEGER VAL2)

Description:

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

Parameters:

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

Return Value:

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

Example:

    INTEGER X, Y;

    FUNCTION MAIN()

    {

      X = SMIN(65535, 0);

      Y = SMIN(25, 26);

    }

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

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Mathematical Functions
SMIN
SMin


# Language Constructs & Functions Overview

Functions take one or more comma separated parameters and return a result. The following template shows how each language construct and function is explained.

Name:

The name used to refer to the construct or function.

Syntax:

The SIMPL+ specific language requirements for this particular construct or function. This section demonstrates exactly how to enter the statement in a SIMPL+ program.

For completeness, the general syntax for SIMPL+ functions is shown below:

    \<Return Value Type\> FunctionName(\<Parameter 1 Type\> [,

    \<Parameter 2 Type\> ...]);

The Types are described as STRING, INTEGER, LONG_INTEGER, SIGNED_INTEGER, and SIGNED_LONG_INTEGER.

If a STRING is specified as a return type, a STRING or STRING_OUTPUT variable may be used.

If an INTEGER or LONG_INTEGER  is specified as a return type, an INTEGER, LONG_INTEGER, ANALOG_OUTPUT or DIGITAL_OUTPUT may be used.

If a STRING is specified as a parameter, a STRING, STRING_INPUT, BUFFER_INPUT or literal string (i.e. "Hello") may be used.

If an INTEGER,  LONG_INTEGER, SIGNED_INTEGER or SIGNED_LONG_INTEGER is specified as a parameter, an INTEGER, LONG_INTEGER, ANALOG_INPUT, ANALOG_OUTPUT, DIGITAL_INPUT or DIGITAL_OUTPUT may be used. A literal integer (i.e. 100) may also be used. Note that for DIGITAL_OUTPUT values, a value of 0 is equivalent to digital low, and any other value is a digital high.

Description:

General overview of what this function does.

Parameters (applies to functions only):

Specifics on each of the parameters listed.

Return Value (applies to functions only):

What values are placed in the return variable. Error conditions are also described here. Error conditions are results that occur if one or more of the input values does not have values that are legal for that function.

Example:

A code example of how this function is typically used.

Version:

The version of SIMPL+ in which the construct or function was made available and any revision notes about differences between various versions of SIMPL+. All constructs and functions are available in all subsequent versions except where noted.

Control System:

The control system platform for which the function is valid. Unless specified, the construct or function is valid for both X-Generation (eg., CEN-TVAV, CNMSX-AV/PRO, CNRACKX/-DP) and 2-Series control systems. SIMPL+ is not available in the control systems preceding the X generation - CNMS, CNRACK/-D/-DP, CNLCOMP/-232, and ST-CP


Program Structure

# Program Structure

When a new SIMPL+ program is created, a template is provided that lists the order in which constructs and statements should be defined. Sections can be uncommented and expanded out to implement the desired code.

A SIMPL+ program layout would consist of, in order:

               1. [Compiler Directives]

               2. Input/Output definitions From/To a SIMPL Program

               3. Global declarations for the module, including STRING, [INTEGER], [Arrays], [Structures], etc.

               4. [FUNCTION] declarations

               5. PUSH/RELEASE/CHANGE statements

               6. FUNCTION MAIN

NOTE:  All of these are not mandatory and may be left out as needed.

NOTE:  In SIMPL+ Version 3.00, local variables are allowed.

Forward references are not allowed in a SIMPL+ program. This means you cannot CALL a function before it has been defined. This is the reason FUNCTION declarations are placed before other code. If function A calls function B, then function B should be located first in the source file.

FUNCTION MAIN is a special case function. It is not required, but any code present between the { and } is executed at startup. This is typically used for initialization purposes. For example:

    FUNCTION MAIN()

    {

      MyVar=0;

      For(I=1 to 10)

         B[I] = I;

    }

Sometimes FUNCTION MAIN() contains an endless loop with a DELAY statement that executes periodically while the program runs.

  [Compiler Directives]: Compiler_Directives/Overview.md
  [INTEGER]: Declarations/INTEGER.md
  [Arrays]: Array_Operations/Arrays.md
  [Structures]: Declarations/STRUCTURES.md
  [FUNCTION]: Functions_Overview.md

Language Constructs & Functions
Program Structure

Arrays CHANGE Compiler DELAY Directives FUNCTION For INTEGER MAIN PUSH Program RELEASE STRING Structure Structures

Compiler Directives
INTEGER
Arrays
Structures
FUNCTION


CompareRampsByAttribute

# CompareRampsByAttribute

Name:

CompareRampsByAttribute

Syntax:

    SIGNED_INTEGER CompareRampsByAttribute (ANALOG_OUTPUT | ANALOG_INPUT signal, RAMP_INFO RampData);

Description:

This function compares the ramping process on the given signal to the ramp described by RampData. Specifically, it checks to make sure that the rampTransitionTime,  rampBaseValue and rampTargetValue are the same.

Parameters:

ANALOG_OUTPUT | ANALOG_INPUT signal RAMP_INFO RampData – the specific analog input or output to test against the described values of RampData in the RAMP_INFO structure.

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

3: There is no ramp process on the specified signal.

1: The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are the same.

0: The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are different.

Example:

In this example, the SIMPL+ module will monitor the input signal.  If the input signal has a ramping process, it will copy it to the output.  It then stores the ramping information for future comparison; each time the input ramp changes, it will trigger this module, but the module will end up stopping once it realizes that it has already processed the ramping process that is on the input.  If there is no ramping process, it will simply copy the input value to the output value.

ANALOG_INPUT InputLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO InputRampInfo, OutputRampInfo;

Change InputLevel

{

  if(IsRamping(InputLevel))

  {

     if(CompareRampsByAttribute(InputLevel, InputRampInfo)=0)

     {

        GetRampInfo(InputLevel, InputRampInfo);

        CreateRamp(OutputLevel, InputRampInfo);

     }

  }

  else

  {

     OutputLevel = InputLevel;

     InitializeRampInfo(InputRampInfo);

  }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
CompareRampsByAttribute()
CompareRampsByAttribute


CompareRampsByID

# CompareRampsByID

Name:

CompareRampsByID

Syntax:

    SIGNED_INTEGER CompareRampsByID (ANALOG_OUTPUT | ANALOG_INPUT signal, LONG_INTEGER ramp_identifier );

Description:

This function compares the ID field of the ramp on the given signal to the [rampIdentifier] member of the RAMP_INFO structure as specified by the RampData variable.

Parameters:

ANALOG_OUTPUT | ANALOG_INPUT signal RAMP_INFO RampData – the specific analog input or output to compare with the RampData in the RAMP_INFO structure.

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

0: The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are different.

1: The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are the same.

3: There is no ramp process on the specified signal.

Example:

This is a more efficient version of the code presented in CompareRampsByAttribute, as all It needs to do is check one long_integer.

ANALOG_INPUT InputLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO InputRampInfo, OutputRampInfo;

LONG_INTEGER InputRampID;

Change InputLevel

{

  if(IsRamping(InputLevel))

  {

     GetRampInfo(InputLevel, InputRampInfo);

     If(InputRampInfo.rampIdentifier \<\> InputRampID)

     {

        CreateRamp(OutputLevel, InputRampInfo);

     }

  }

  else

  {

     OutputLevel = InputLevel;

     InitializeRampInfo(InputRampInfo);

  }

}

function main()

{

   // By initializing our test-against ID to zero, we will guarantee that the first

   // time a ramp is found in the change statement, the ramps will not be thought to

   // be the same.

   InputRampID = 0;

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [rampIdentifier]: Ramping_Functions.md
  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
CompareRampsByID()
CompareRampsByID


CreateRamp

# CreateRamp

Name:

CreateRamp

Syntax:

    SIGNED_INTEGER CreateRamp (ANALOG_OUTPUT signal, RAMP_INFO RampData);

Description:

Creates a ramping process on the specific ANALOG_OUTPUT. If the output already has a running ramping process on it this function will modify that process regardless of its origin. (e.g., rampTransitionTime could be increased or rampTargetValue could be reduced). The following members must be filled in by the user:

rampLowerBound

rampUpperBound

rampBaseValue

rampTargetValue

rampTransitionTime

rampIsAbsolute

rampIsRunnable

NOTE: See [Ramping Functions Defaults] for the default values of these members.

Parameters:

ANALOG_OUTPUT signal – the specific output on which to create the ramping process. It is legal to use an ANALOG_OUTPUT or an element of an ANALOG_OUTPUT array.

RAMP_INFO RampData – a declared variable of RAMP_INFO used to hold information about the created ramping process.

NOTE:  This function will change the following user-defined values in the RAMP_INFO structure: \
\
rampIsAbsolute: will be changed to 1 (Absolute) if the user specified that it would be Relative (\<\>1).\
\
rampTransitionTime: will be changed to the Absolute Transition Time reported by ANALOG_OUTPUT signal if the user originally specified rampTransitionTime as Relative (\<\>1).\
\
rampBaseValue: will be set to the value reported by ANALOG_OUT signal if rampBaseValue has been set to 100000.

NOTE:  This function will fill in the following non-user specifiable values in the RAMP_INFO structure: \
\
rampBaseTime: will be automatically set to the system time at which the ramp was created.\
\
rampIdentifier: will be automatically set to distinguish the current ramp from any other existing ramps.\

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

0: Ramping process created or modified successfully.

Example:

In this example, an analog output array element is given a ramping process that will ramp from signal's current value to 10% (6553) in 10 seconds (1000).

DIGITAL_INPUT GoToPresetLevel;

ANALOG_OUTPUT LightLevel[20];

PUSH GoToPresetLevel

{

   RAMP_INFO LightInfo;

   SIGNED_INTEGER status;

   // 10% of 65535 is 6553.

   LightInfo.rampTargetValue=6553;

   // Always takes "rampTransitionTime" to go to the Target Value.

   LightInfo.isAbsolute=1;

   // Transition time of 10 seconds (1000 hundredths of a second)

   LightInfo.rampTransitionTime=1000;

   If(IsSignalDefined(LightLevel[1])

   {

     status = CreateRamp(LightLevel[1], LightInfo);

     if(status \<\> 0)

        GenerateUserWarning("Could not create Ramping Process, status = %d", status);

   }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Functions Defaults]: javascript:void(0);
  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
CreateRamp()
CreateRamp

ANALOG_OUTPUT CreateRamp DIGITAL_INPUT GenerateUserWarning If IsSignalDefined PUSH Relative SIGNED_INTEGER


GetRampInfo()

# GetRampInfo()

Name:

GetRampInfo()

Syntax:

    SIGNED_INTEGER GetRampInfo (ANALOG_OUTPUT | ANALOG_INPUT signal, RAMP_INFO RampData)

Description:

This function populates the fields of the given RAMP_INFO structure with the information from the ramping process on the given output signal.

Parameters:

ANALOG_OUTPUT | ANALOG_INPUT signal RAMP_INFO RampData

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

0: The info on the ramping process on a given output was obtained successfully and placed into the RAMP_INFO structure.

3: There is no ramp process on the specified signal.

Example:

ANALOG_INPUT InputLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO InputRampInfo, OutputRampInfo;

Change InputLevel

{

  if(IsRamping(InputLevel))

  {

     if(CompareRampsByAttribute(InputLevel, InputRampInfo)=0)

     {

        GetRampInfo(InputLevel, InputRampInfo);

        CreateRamp(OutputLevel, InputRampInfo);

     }

  }

  else

  {

     OutputLevel = InputLevel;

     InitializeRampInfo(InputRampInfo);

  }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
GetRampInfo()


InitializeRampInfo()

# InitializeRampInfo()

Name:

InitializeRampInfo()

Syntax:

    InitializeRampInfo(RAMP_INFO val)

Description:

Initializes the given RAMP_INFO structure to it's default state.  The value can be either an arrayed or non-arrayed structure.  The default states are the same as when the RAMP_INFO structure is declared. Refer to [Ramping Function Defaults].

This is useful for returning the structure back to a safe state after performing comparisons.  (see CompareRampsByAttribute(), CompareRampsByID()).

Parameters:

RAMP_INFO val: – the variable "val" of the type RAMP_INFO is initialized.

Return Value:

None

Example:

ANALOG_INPUT InputLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO InputRampInfo, OutputRampInfo;

Change InputLevel

{

  if(IsRamping(InputLevel))

  {

     if(CompareRampsByAttribute(InputLevel, InputRampInfo)=0)

     {

        GetRampInfo(InputLevel, InputRampInfo);

        CreateRamp(OutputLevel, InputRampInfo);

     }

  }

  else

  {

     OutputLevel = InputLevel;

     InitializeRampInfo(InputRampInfo);

  }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Function Defaults]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
InitializeRampInfo
InitializeRampInfo()

ANALOG_INPUT ANALOG_OUTPUT CompareRampsByAttribute CompareRampsByID CreateRamp GetRampInfo InitializeRampInfo IsRamping


InitializeRampInfoArray()

# InitializeRampInfoArray()

Name:

InitializeRampInfoArray()

Syntax:

    InitializeRampInfoArray(RAMP_INFO array[])

Description:

Initializes each structure the given RAMP_INFO array to it's default state. The default states are the same as when the RAMP_INFO structure is declared:

rampUpperBound:  65535

rampLowerBound:  0

rampBaseValue:  100000

rampTargetValue:  65535

rampBaseTime:  0

rampTransitionTime:  0

rampIsSigned:  0

rampIsAbsolute:  0

This is useful for returning the structure back to a safe state after performing comparisons.  (see CompareRampsByAttribute(), CompareRampsByID()).

Parameters:

RAMP_INFO array[ ] – a RAMP_INFO array is initialized.

Return Value:

None

Example:

ANALOG_INPUT InputLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO InputRampInfo, OutputRampInfo;

Change InputLevel

{

  if(IsRamping(InputLevel))

  {

     if(CompareRampsByAttribute(InputLevel, InputRampInfo)=0)

     {

        GetRampInfo(InputLevel, InputRampInfo);

        CreateRamp(OutputLevel, InputRampInfo);

     }

  }

  else

  {

     OutputLevel = InputLevel;

     InitializeRampInfo(InputRampInfo);

  }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

Language Constructs & Functions
Ramping Functions
InitializeRampInfoArray()

ANALOG_INPUT ANALOG_OUTPUT CompareRampsByAttribute CompareRampsByID CreateRamp GetRampInfo InitializeRampInfo InitializeRampInfoArray IsRamping


IsRamping

# IsRamping

Name:

IsRamping

Syntax:

    SIGNED_INTEGER IsRamping (ANALOG_OUTPUT | ANALOG_INPUT signal);

Description:

This function determines if there is a ramping process present on the specified  ANALOG_OUTPUT signal.

Parameters:

ANALOG_OUTPUT | ANALOG_INPUT signal – the specific analog input or output to test for the presence of a ramping process.

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

1: There is a ramping process present on the specified signal.

3: There is no ramping process present on the specified signal.

Example:

In this example, the SIMPL+ module will start a ramping transition on the analog output "LightingLevel" using the default RAMP_INFO structure values, only if there is no ramping process currently on it (i.e. an "Analog Ramp" symbol or other ramp-generating symbol currently has a ramping operation in progress on that analog output signal in SIMPL).

DIGITAL_INPUT StartFade;

ANALOG_INPUT LightingLevel;

ANALOG_OUTPUT OutputLevel;

RAMP_INFO LightInfo;

Push StartFade

{

   if(IsRamping(LightingLevel) != 1)

   {

CreateRamp(OutputLevel, LightInfo);

   }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
IsRamping()
IsRamping


RAMP_INFO Structure

# RAMP_INFO Structure

These are the default values for the RAMP_INFO structure.

|                    |         |
|--------------------|---------|
| MEMBER             | DEFAULT |
| rampLowerBound     | 0       |
| rampUpperBound     | 65535   |
| rampBaseValue      | 100000  |
| rampTargetValue    | 65535   |
| rampTransitionTime | 500     |
| rampIsAbsolute     | 0       |
| rampIsRunnable     | 1       |
| rampIdentifier     | 0       |
| rampBaseTime       | 0       |

Language Constructs & Functions
Ramping Functions
RAMP INFO Structure
RAMP_INFO Structure


Ramping Function Return Error Codes

# Ramping Function Return Error Codes

|  |  |  |
|----|----|----|
| KEYWORD | VALUE | FUNCTION |
| RAMP_ILLEGAL_BASE_VALUE | -22 | rampBaseValue is not within the bounds of rampUpperBound to rampLowerBound |
| RAMP_ILLEGAL_TARGET_VALUE | -21 | rampTargetValue is not within the bounds of rampUpperBound to rampLowerBound |
| RAMP_BOUNDS | -20 | Illegal bounds have been specified. Bounds must be -32768 to 32767 or 0 to 65535. An error message is placed in the error log. |
| RAMP_INVALID | -15 | Invalid Ramp (Internal, Contact Crestron) |
| RAMP_NO_CREATE | -14 | Could Not Create Ramp (Internal, Contact Crestron) |
| RAMP_BAD_POINTER | -13 | Illegal internal Ramp Pointer (Internal, Contact Crestron) |
| RAMP_ILLEGAL_ISABSOLUTE | -12 | Illegal value specified for rampIsAbsolute, must be 0 or 1. |
| RAMP_NO_SIGNAL | -8 | No signal at given index.1 |
| RAMP_SUCCESS | 0 | Ramping process created/modified successfully |
| RAMP_DIFFERENT_RAMP2 | 0 | The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are the different. |
| RAMP_RAMP_PRESENT | 1 | Ramp present on the given signal |
| RAMP_SAME_RAMP2 | 1 | The ramping process on the specified signal and the data specified in the given RAMP_INFO structure are the same. |
| RAMP_NO_RAMP | 2 | No Ramp on the signal to stop |
| RAMP_NO_RAMP_PRESENT | 3 | No Ramp on the given signal |

1.  This would typically happen if an element of an ANALOG_OUTPUT array is used that is not defined on the SIMPL symbol.  For example, ANALOG_OUTPUT levels[20]; is in the SIMPL+ program, and the symbol is only expanded to 5, but an attempt is made to create a ramping process on levels[15].

2.  Applies to CompareRampByAttribute and CompareRampsByID. only.

Language Constructs & Functions
Ramping Functions
Ramping Function Return Error Codes

ANALOG_OUTPUT Codes Error FUNCTION Function Pointer Ramp Ramping Return


Ramping Functions (Part 1)

# Ramping Functions

Ramping functions make it possible to manage processes that smoothly transition an ANALOG_OUTPUT from one value to another over a specified period of time. In the past, it was necessary to use methods such as loops to issue multiple values or an oscillator to trigger a DIGITAL_INPUT to increment an ANALOG_OUTPUT in order to get the same effect. Functions are available for creation, destruction, detection and comparison.

The Ramping functions use a pre-defined structure called RAMP_INFO.

    STRUCTURE RAMP_INFO

        {

             SIGNED_LONG_INTEGER    // rampLowerBound;

             SIGNED_LONG_INTEGER    // rampUpperBound;

             SIGNED_LONG_INTEGER    // rampBaseValue;

             SIGNED_LONG_INTEGER    // rampTargetValue;

             INTEGER                // rampIsAbsolute;

             LONG_INTEGER           // rampTransitionTime;

             INTEGER                // rampIsRunnable;

             LONG_INTEGER           // rampIdentifier;

             LONG_INTEGER           // rampBaseTime;

             INTEGER                // rampIsSigned;

             INTEGER                // rampIsExpired;

        };

NOTE: Your choice of values for rampLowerBound, rampUpperBound, rampBaseValue and rampTargetValue must be consistent within a given RAMP_INFO function (shown later in this topic). Choose either the -32768 to 32767 range or the 0 to 65535 range.

The members of RAMP_INFO are described as follows:

Language Constructs & Functions
Ramping Functions
Ramping Functions
Ramping Functions


Ramping Functions (Part 2)

| MEMBER             | DESCRIPTION                                                                                | NOTES                                                                                |
| ------------------ | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rampLowerBound     | The lowest possible value of the ramp.                                                                          | Legal values are -32768 to 32767 or 0 to 65535. Default is 0.                                                                                |
| rampUpperBound     | The highest possible value of the ramp.                                                                         | Legal values are -32768 to 32767 or 0 to 65535. Default is 65535.                                                                                |
| rampBaseValue      | The starting value of the ramp.                                                                                | Legal values are -32768 to 32767 or 0 to 65535. Default is 1000001. The ramp will start from the current value of the signal on the ANALOG_OUT in SIMPL. The predefined constant; SIGNAL_DEFAULT_VALUE can also be used.                                                                                |
| rampTargetValue    | The ending value of the ramp.                                                                                | Legal values are -32768 to 32767 or 0 to 65535. Default is 65535.                                                                                |
| rampTransitionTime | The length of time (in units of 0.01sec.) for the ramping function to go from rampBaseValue to rampTargetValue. | The rampTransitionTime is dependent on the value of the rampIsAbsolute member. Default is 5002.                                                                                |
| rampIsAbsolute     | Indicates whether or not the rampTransitionTime is relative (indicated by <>1) or absolute (indicated by 1).    | If rampTransitionTime is relative, the rampTransitionTime will be the result of the following formula: If rampTransitionTime is absolute, the time to get from rampBaseValue to rampTargetValue is exactly as specified. Default is 0 (FALSE). Legal values are 0 and 1.                                                                                |
| rampIsRunnable     | Specifies if the ramp actually creates values to put into a signal or if the ramp is a place holder.            | If a SIMPL+ module is creating a ramp, like the Analog Ramp symbol does, then IsRunnable is 1. If the SIMPL+ module is looking at a ramp on an ANALOG_INPUT and then placing one on an ANALOG_OUTPUT, it should set IsRunnable=0, and the module itself should be responsible for setting the correct discrete value on the analog output. Default is 1 (TRUE). |
| rampIdentifier     | Used to distinguish one ramp from another where two ramps are in use.                                           | Since two ramps can be created at the same time and have the same start/end values and rampTransitionTime, this member is used to distinguish one ramp from another. The system assigns the rampIdentifier. It is not user-specifiable.                                                                                |
| rampBaseTime       | The system time at which the ramping process was created.                                                       | This member is not user-specifiable.                                                                                |
| rampIsSigned       |                                                                                |                                                                                |
| rampIsExpired      |                                                                                |                                                                                |

Choose either the -32768 to 32767 range or the 0 to 65535 range. The members of RAMP_INFO are described as follows:


Ramping Functions (Part 3)

1.  The rampBaseValue default of 100000 is not a legal value for an analog signal (legal values are -32768 to 32767 or 0 to 65535). The default of 100000 means that when the ramp is launched it's value--the 100000--is replaced by the existing rampBaseValue from the ANALOG_OUTPUT signal parameter called by the [CreateRamp] function.

2.  In SIMPL+ time is rendered in hundredths of a second. Therefore, 5 seconds is represented as 500.

The functions available to the RAMP_INFO structure are:

[CreateRamp]

[StopRamp]

[IsRamping]

[GetRampInfo]

[CompareRampsByAttribute]

[CompareRampsByID]

[InitializeRampInfo]

[InitializeRampInfoArray]

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [CreateRamp]: CreateRamp().md
  [StopRamp]: StopRamp().md
  [IsRamping]: IsRamping().md
  [GetRampInfo]: GetRampInfo().md
  [CompareRampsByAttribute]: CompareRampsByAttribute().md
  [CompareRampsByID]: CompareRampsByID().md
  [InitializeRampInfo]: InitializeRampInfo.md
  [InitializeRampInfoArray]: InitializeRampInfoArray().md

ANALOG_OUTPUT CompareRampsByAttribute CompareRampsByID CreateRamp Functions GetRampInfo InitializeRampInfo InitializeRampInfoArray IsRamping Part Ramping StopRamp

CreateRamp StopRamp IsRamping GetRampInfo CompareRampsByAttribute CompareRampsByID InitializeRampInfo InitializeRampInfoArray

| This member is not user-specifiable. |
| rampIsSigned       |                                                                                |                                                                                |
| rampIsExpired      |                                                                                |                                                                                |


StopRamp

# StopRamp

Name:

StopRamp

Syntax:

    SIGNED_INTEGER StopRamp (ANALOG_OUTPUT signal);

Description:

This function unconditionally terminates, or stops, the ramping process on a given ANALOG_OUTPUT signal.

Parameters:

ANALOG_OUTPUT signal – the specific output of the ramping process you want to stop. It is legal to use an ANALOG_OUTPUT or an element of an ANALOG_OUTPUT array.

Return Value:

If the return value is negative, it is an error code. (see [Ramping Functions Error Codes])

The returned values for this function are as follows:

2: There is no Ramp Control Block (RCB) to stop on the specified signal.

0: RCB stopped successfully.

Example:

In this example, when TerminateFade is driven high, the SIMPL+ module will stop the fade in progress on the Light driven by analog output LightLevel[1].

DIGITAL_INPUT TerminateFade;

ANALOG_OUTPUT LightLevel[20];

PUSH TerminateFade

{

   SIGNED_INTEGER status;

   if(IsSignalDefined(LightLevel[1]))

   {

      status = StopRamp(LightLevel[1]);

      if(status \< 0)

         GenerateUserWarning("Error stopping ramping process, status = %d", status);

   }

}

Version:

SIMPL Version 2.10.00 or later

SIMPL+ Version 3.03.00 or later

2-series only, CUZ 4.000 or later

  [Ramping Functions Error Codes]: javascript:void(0);

Language Constructs & Functions
Ramping Functions
StopRamp()
StopRamp


Random Number Functions Overview

# Random Number Functions Overview

These functions allow a SIMPL+ program to generate a random number.

Language Constructs & Functions
Random Number Functions
Overview
Random Number Functions Overview


Random

# Random

Name:

Random

Syntax:

    INTEGER Random(INTEGER LowerBound, INTEGER UpperBound);

Description:

Generate a random number. See also: [Seed] and [Rnd].

Parameters:

LowerBound is an INTEGER specifying the lower end of the range.

UpperBound is an INTEGER specifying the upper end of the range.

Both LowerBound and UpperBound are treated as unsigned values.

Return Value:

Returns an unsigned number from LowerBound to UpperBound. Both LowerBound and UpperBound are legal values.

Example:

    INTEGER NUM;

    FUNCTION MAIN()

    {

      NUM = RANDOM(25, 80);

      PRINT("The random number between 25 and 80 is: %u\n", NUM);

    }

An example output from this would be:

    The random number between 25 and 80 is: 42

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

  [Seed]: SEED.md
  [Rnd]: RND.md

Language Constructs & Functions
Random Number Functions
RANDOM
Random

FUNCTION INTEGER MAIN PRINT RANDOM Random Rnd Seed


Rnd

# Rnd

Name:

Rnd

Syntax:

    INTEGER Rnd();

Description:

Generate a random number. See also: [Seed] and [Random].

Parameters:

None.

Return Value:

An INTEGER from 0 to 65535.

Example:

    INTEGER NUM;

    FUNCTION MAIN()

    {

      NUM = RND();

      PRINT("The random number is: %u\n", NUM);

    }

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

  [Seed]: SEED.md
  [Random]: RANDOM.md

Language Constructs & Functions
Random Number Functions
RND
Rnd

FUNCTION INTEGER MAIN PRINT RANDOM RND Random Rnd Seed


Seed

# Seed

Name:

Seed

Syntax:

    Seed(INTEGER SeedValue);

Description:

Provides a seed or origin for the random number generator so that the numbers returned by RND and RANDOM are pseudo-random numbers. SEED is not required for generating random numbers as the random number generator will be seed with a default value.  This default value is issued at control system restart, not program restart.  That is, if you don't used the SEED call, you will not get the same value if you restart the program.  For any particular value of SEED, the random number generator will generate a predictable series of numbers. Note that specifying the seed value is global to all SIMPL+ programs running inside a control system. The sequence begins again whenever SEED is called.

Parameters:

None.

Return Value:

None.

Example:

    INTEGER NUM;

    FUNCTION MAIN()

    {

      SEED(25);

      NUM = RANDOM(25, 80);

      PRINT("The random number between 25 and 80 is: %u\n", NUM);

    }

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
Random Number Functions
SEED
Seed

FUNCTION INTEGER MAIN PRINT RANDOM SEED Seed


MakeString

# MakeString

Name:

MakeString

Syntax:

    MakeString(STRING DESTINATION, \<Static Specification

               String\> [, \<arg1\> ...]);

    MakeString(0 | 1 | 2, \<Static Specification String\> [,

               \<arg1\> ...]);

Description:

MAKESTRING is a variant of [PRINT]. The output of MAKESTRING goes to the DESTINATION string. It can print simple text strings or complex formatted strings. The second form of MAKESTRING allows different destinations to be selected:

0:  Console Port, same as PRINT.

1:  CPU (same functionality as SendPacketToCPU function)

2:  Cresnet Network (same functionality as SendCresnetPacket function).

NOTE:  In the second form, the first argument may not be a variable containing 0, 1, 2. It must be the written as 0, 1, 2. Crestron is discouraging the use of the second form of MAKESTRING in favor of either the PRINT command or alternate methods for activating devices that do not require knowledge of Cresnet packets, which are subject to change.

Parameters:

DESTINATION is a string where the output goes to after it has been formatted and processed. For a further description of formatting, refer to [PRINT].

Return Value:

None.

Example:

    INTEGER X;

    STRING Z[100], OUT[100];

    X=10;

    Z="Hello";

    FUNCTION MAIN()

    {

      // Puts "This is a string" followed by a CRLF onto OUT.

      MAKESTRING(OUT, "This is string\n");

      // Puts "The value of X is 10 in decimal, 0A in hex"

      // followed by CRLF onto OUT.

      MAKESTRING(OUT, "The value of X is %u in decimal, %02X in

      hex\n", X, X);

      // Puts "The String value is Hello" onto OUT.

      MAKESTRING(OUT, "The String value is %s", Z);

    }

Version:

X Generation

SIMPL v1.20.01 and later

SIMPL v1.50.06 and later, adds Console, Cresnet, and CPU destinations.

2-Series

SIMPL v2.01.05 and later, [Same as X Generation SIMPL v1.50.06], but allows %c format specifier.

  [PRINT]: PRINT.md

Language Constructs & Functions
String Formatting & Printing Functions
MAKESTRING
MakeString

CPU FUNCTION INTEGER MAIN MAKESTRING MakeString Network PRINT STRING


# String Formatting & Printing Functions Overview

The printing functions are used to take INTEGER and STRING type arguments in a SIMPL+ program, format them in a user specified way, and send the output to either the CONSOLE of the control system or to another STRING.

The functions are:

[MakeString]

[Print]

[String Concatenation]

[String Operators]

[Trace]

  [MakeString]: MAKESTRING.md
  [Print]: PRINT.md
  [String Concatenation]: STRING_CONCATENATION.md
  [String Operators]: String_Operators.md
  [Trace]: TRACE.md

Concatenation Formatting Functions INTEGER MAKESTRING MakeString Operators Overview PRINT Print Printing STRING String TRACE Trace

MakeString
Print
String Concatenation
String Operators
Trace


Print (Part 1)

# Print

Name:

Print

Syntax:

    PRINT(\<Static Specification String\> [, \<arg1\> ...]);

Description:

The output of PRINT goes to the CONSOLE of the control system and can be monitored in the Crestron Viewport. It can print simple text strings or complex formatted strings. (See also [TRACE])

Parameters:

\<Static Specification String\> is a quoted string that contains text and formatting information. Format specifiers are of the form:

    %[[Pad]Width]specifier

Valid format specifiers are:

s:  Specifies a BUFFER_INPUT, STRING, or STRING_INPUT variable (unprintable characters are printed in the format that Viewport uses).

d:  Specifies an ANALOG_INPUT, ANALOG_OUTPUT, or INTEGER to be printed as a signed decimal value.

u:  Specifies an ANALOG_INPUT, ANALOG_OUTPUT, or INTEGER to be printed as an unsigned decimal value.

x:  Specifies an ANALOG_INPUT, ANALOG_OUTPUT, or INTEGER to be printed as a lowercase hexadecimal number.

X:  Specifies an ANALOG_INPUT, ANALOG_OUTPUT, or INTEGER to be printed as an uppercase hexadecimal number.

l: Specifies a LONG_INTEGER or UNSIGNED_LONG_INTEGER will follow, and is followed by d, u, x, or X.

%:  Prints a % sign (i.e. use %% to print a % sign).

%ld: Specifies a LONG_INTEGER to be printed as a signed decimal value.

%c: Specifies a printable ASCII character to be printed.

The optional Width specifier is a number that states the width of the field as characters. If the value to be printed is less than the Width, it is padded on the left with spaces for alpha-characters and zeros for numeric characters. (Width can be two digits).

The optional Pad specifier works with the Width specifier. If the result of the Width operation results in the need to add spaces, the Pad specifier can be used to pad with different values rather than a space. '0' is the only valid pad value, i.e., %03d pads with leading zeros so 1Z would be printed as 012.

As each % value is found, it pulls the matching \<arg\> off the list. The first % uses \<arg1\>, the second % uses \<arg2\>, etc. If the number of % specifiers does not match the number of arguments, the program will generate a compile error. The compiler also checks to make sure the format specifier matches the type of the variable being used (i.e. if %d is used, the variable being used should be INTEGER type).

NOTE:  If no format specifiers are used, then a simple quoted text string is printed.

NOTE:  The total string length that can be guaranteed to print is 256 characters.  \
For example:

string a[500], b[500];

a = " { A STRING WITH 200 CHARACTERS } ";

b = " { A STRING WITH 56 CHARACTERS } ";

print("%s%s", a,b);

You would see all 256 characters.

If the total adds up to greater than 256 characters, it is possible that more may be seen, but only 256 is guaranteed.  [MAKESTRING()] does not have this limitation.

NOTE:  Hex sequence characters within the format specifier will be translated into the equivalent ascii character before the format specifier is translated.  For example, Print( "\x25%s", "abc" );, will NOT result in printing "%abc".  The result will be "%s" since the compiler will translate the \x25 to the % character first  (the Print statement will become Print( "%%s", "abc");)

Language Constructs & Functions
String Formatting & Printing Functions
PRINT
Print


Print (Part 2)

In the \<Static Specification String\>, certain values may be printed using "escape sequences". Escape sequences start with the \\ character and have a variable number of characters following. The following table specifies the legal escape sequences:

|        |                                                |              |
|--------|------------------------------------------------|--------------|
| ESCAPE | MEANING                                        | HEX CONSTANT |
| \n     | Carriage Return + Linefeed                     | \x0D\0A      |
| \t     | Tab                                            | \x09         |
| \b     | Backspace                                      | \x08         |
| \r     | Carriage Return                                | \x0D         |
| \f     | Form Feed                                      | \x0C         |
| \a     | Audible Alert (Bell)                           | \x07         |
| \\     | Backslash                                      | \x5C         |
| \\     | Single Quote                                   | \x27         |
| \\     | Double Quote                                   | \x22         |
| \xZZ   | Hex Constant. Z can range from 0-9, a-f or A-F | \xZZ         |

Return Value:

None.

Example:

    INTEGER X;

    STRING Z[100];

    X=10;

    Z="Hello";

    FUNCTION MAIN()

    {

      // Outputs "This is a string" followed by a CRLF.

      PRINT("This is a string\n");

      // Outputs "The value of X is 10 in decimal, 0A in hex"

      // followed by CRLF.

      PRINT("The value of X is %u in decimal, %02X in hex\n",

      X, X);

      // Outputs "The String value is Hello"

      PRINT("The String value is %s", Z);

    }

Version:

X Generation

SIMPL v1.20.01 and later

2-Series

SIMPL v2.01.05 and later, [Same as X Generation SIMPL v1.20.01], but allows %c format specifier.

  [TRACE]: TRACE.md
  [MAKESTRING()]: MAKESTRING.md

Alert FUNCTION INTEGER MAIN MAKESTRING PRINT Part Print STRING TRACE

For example, Print( "\x25%s", "abc" );, will NOT result in printing "%abc". The result will be "%s" since the compiler will translate the \x25 to the % character first  (the Print statement will become Print( "%%s", "abc");)


STRING CONCATENATION

# STRING CONCATENATION

String concatenation can be performed either using the + operator or by using MAKESTRING or PRINT functions. It is easier to use the + operator in general usage, although the formatting options of the MAKESTRING and PRINT functions give greater flexibility.

The + operator for strings is used the same way as in mathematical expressions. String concatenation may only be used as a standalone statement. The syntax is:

\<Destination_string\> = \<String1 \> [+ \<String2\> ...];

When string values appear on the right-side of the equal sign, the exact contents are appended to the new string. \<String\> values may be of type literal (quoted) strings, BUFFER_INPUT, STRING, STRING_INPUT, or any function that returns a string.

Examples:

INTEGER I;

INTEGER J;

STRING A$[100], B$[100], C$[100];

    B$="Hello";

    C$="World!";

    I=56;

    J=2;

    // This will output "Hello562xyzWorld!"

    A$=B$+ITOA(I)+ITOA(J)+"xyz"+C$;

    PRINT("%s", A$);

    // This will output "8Hello2World"

    A$=CHR(I)+B$+ITOA(J)+C$;

    PRINT("%s", A$);

Language Constructs & Functions
String Formatting & Printing Functions
STRING CONCATENATION

BUFFER_INPUT CHR CONCATENATION INTEGER ITOA MAKESTRING PRINT STRING STRING_INPUT


String Operators

# String Operators

String Operators

|          |              |              |                                     |
|----------|--------------|--------------|-------------------------------------|
| OPERATOR | NAME         | EXAMPLE      | EXPLANATION                         |
| =        | Assignment   | A$ = B$    | Assigns the contents in B$ to A$. |
| =        | Comparison   | A$ = B$    | A$ equal B$                       |
| \<\>     | Not Equal To | A$ \<\> B$ | A$ is not equal to B$             |
| \<       | Less Than    | A$ \< B$   | A$ is less than B$                |
| \>       | Greater Than | A$ \> B$   | A$ is greater than B$             |

For less than and greater than operations, the string is evaluated in ASCII order. For example, the comparison "ABC" \> "ABD" would be false. The system looks character by character; the first two characters are identical in both strings, and when it evaluated the characters C (ASCII 67) vs. D (ASCII 68), the result is false. The comparison "ABC" \< "ABCD" is true, because a shorter string alphabetically precedes one that is identical but longer.

Language Constructs & Functions
String Formatting & Printing Functions
String Operators


TRACE

# TRACE

Name:

Trace

Syntax:

    TRACE(\<Static Specification String\> [, \<arg1\> ...]);

Description:

The output of TRACE goes to the CONSOLE of the control system and can be monitored in the Trace window in the Crestron Toolbox SIMPL Debugger and in Crestron Viewport. It can display simple text strings or complex formatted strings.

NOTE: PRINT() and TRACE() are equivalent, with the exception that TRACE prepends the hex  characters \xFA\xE0, and suffixes the string with \xFB - and with the exception of how the  compiler directives #ENABLE_TRACE and #PRINT_TO_TRACE deal with the print() and trace() statements.

See also [Print] and [#ENABLE_TRACE] and [#PRINT_TO_TRACE] for more information.

Version:

2-Series

SIMPL v2.10.09 and later, [Same as X Generation SIMPL v1.20.01], but allows %c format specifier.

  [Print]: PRINT.md
  [#ENABLE_TRACE]: ../Compiler_Directives/_ENABLE_TRACE.md
  [#PRINT_TO_TRACE]: ../Compiler_Directives/_PRINT_TO_TRACE.md

Language Constructs & Functions
String Formatting & Printing Functions
TRACE


ClearBuffer

# ClearBuffer

Name:

ClearBuffer

Syntax:

    ClearBuffer(STRING BUFFERNAME);

Description:

Deletes the contents of the specified buffer. If a LEN is done on the buffer after a CLEARBUFFER, the return value will be 0. This is equivalent to assigning an empty string to the buffer, e.g., BUFFERNAME="";

Parameters:

BUFFERNAME specifies the name of the string to empty. BUFFER_INPUT, STRING, and STRING_INPUT sources are legal.

Return Value:

None.

Example:

    BUFFER_INPUT IN$[100];

    CHANGE IN$

    {

      IF(RIGHT$(IN$,1) = "Z")

        CLEARBUFFER(IN$);

      // Code to process IN$ goes here.

    }

In this example, if the last character that comes into the BUFFER_INPUT is "Z", the buffer is cleared.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
CLEARBUFFER
ClearBuffer

BUFFER_INPUT CHANGE CLEARBUFFER ClearBuffer IF LEN RIGHT STRING STRING_INPUT


CompareStrings

# CompareStrings

Name:

CompareStrings

Syntax:

    SIGNED_INTEGER CompareStrings(STRING string1, STRING string2);

Description:

Performs a case-sensitive comparison of string1 and string2.  This function can be used in place of the "=", "\<", "\>", "\<\>" operators. The comparison is done in ASCII order (e.g., the string "ABC" is less than "ABD" and the string "abc" is greater than "ABC" since the character 'a' comes after 'A' in the ASCII table).

Parameters:

STRING string1:  First string to use in the comparison

STRING string2:  Second string to use in the comparison

Return Value:

\< 0: indicates that string1 is less than string2 in ASCII order.

0: indicates that string1 is equal to string2 in ASCII order.

\> 0: indicates that string1 is greater than string2 in ASCII order.

Example:

    STRING FirstString, SecondString;

    SIGNED_INTEGER result;

    FirstString = "ValueA";

    SecondString = "Valueb";

    result = CompareStrings(FirstString, SecondString);

    Print("Result is %d.\n", result);

Since the first 5 characters are the same, the result comes down to comparing 'A' and 'b'.  Since the ASCII value of 'b' (0x62) is greater than the ASCII value of 'A' (0x41), the result is string1 \> string2.  The output of the function is –1, so the Print statement prints: "Result is 1."

Version:

SIMPL+ Version 3.03.00 or later

CUZ 3.137 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
CompareStrings

CompareStrings Print SIGNED_INTEGER STRING


CompareStringsNoCase

# CompareStringsNoCase

Name:

CompareStringsNoCase

Syntax:

    SIGNED_INTEGER CompareStringsNoCase(STRING string1, STRING string2);

Description:

Performs a case-insensitive comparison of string1 and string2. The strings are internally converted to uppercase before the comparison is done.  The original strings passed into the function are not modified.  The comparison is done in ASCII order. (e.g., the string "ABC" is less than "ABD" however the string "AbC" and "aBC" are the same, since the comparison is case insensitive).

Parameters:

STRING string1:  First string to use in the comparison

STRING string2:  Second string to use in the comparison

Return Value:

-1: indicates that string1 is less than string2 in ASCII order.

0: indicates that string1 is equal to string2 in ASCII order.

1: indicates that string1 greater than string2 in ASCII order.

Example:

    STRING FirstString, SecondString;

    SIGNED_INTEGER result;

    FirstString = "Valuea";

    SecondString = "Valueb";

    result = CompareStringsNoCase(FirstString, SecondString);

    Print("Result is %d.\n", result);

The strings are internally converted to "VALUEA" and "VALUEB".  Since the first 5 characters are the same, the result comes down to comparing 'A' and 'B'.  Since the ASCII value of 'A' (0x41) is less than the ASCII value of 'B' (0x42), the result is string1 \< string2.  The output of the function is –1, so the Print statement prints: "Result is –1."

Version:

SIMPL+ Version 3.03.00 or later

CUZ 3.137 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
CompareStringsNoCase

CompareStringsNoCase Print SIGNED_INTEGER STRING


Find

# Find

Name:

Find

Syntax:

    INTEGER Find(STRING MATCH_STRING, STRING SOURCE_STRING

                 [,INTEGER START_POSITION]);

Description:

Finds the position in SOURCE_STRING where MATCH_STRING first occurs. The search is case sensitive.

Parameters:

MATCH_STRING is a STRING containing the string to be matched.

SOURCE_STRING is a STRING containing the string to be searched.

START_POSITION is an INTEGER which tells FIND at what character in the string to start the search, and is 1 based. If it is not specified, it defaults to 1.

Return Value:

The index of where MATCH_STRING first occurs (going left to right) in SOURCE_STRING. If a match can not be found, or POSITION exceeds the length of the SOURCE_STRING then 0 is returned. The index is 1 based.

Example:

    STRING_INPUT IN$[100];

    INTEGER START_LOC;

    CHANGE IN$

    {

      START_LOC = FIND("XYZ", IN$);

      PRINT("XYZ was found starting at position %d in %s\n",

      START_LOC, IN$);

    }

If IN$ was set equal to "Hello, World!" then START_LOC would be 0 since "XYZ" can not be found. If IN$ was equal to "CPE1704XYZXYZ", then START_LOC would be equal to 8.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
FIND
Find

CHANGE FIND Find INTEGER PRINT STRING STRING_INPUT


FindNoCase

# FindNoCase

Name:

FindNoCase

Syntax:

    INTEGER FindNoCase(STRING MATCH_STRING, STRING SOURCE_STRING

                 [,INTEGER START_POSITION]);

Description:

Finds the position in SOURCE_STRING where MATCH_STRING first occurs. The search is case insensitive.

Parameters:

MATCH_STRING is a STRING containing the string to be matched.

SOURCE_STRING is a STRING containing the string to be searched.

START_POSITION is an INTEGER which tells FINDNOCASE at what character in the string to start the search, and is 1 based. If it is not specified, it defaults to 1.

Return Value:

The index of where MATCH_STRING first occurs (going left to right) in SOURCE_STRING. If a match can not be found, or POSITION exceeds the length of the SOURCE_STRING then 0 is returned. The index is 1 based.

Example:

    STRING_INPUT IN$[100];

    INTEGER START_LOC;

    CHANGE IN$

    {

      START_LOC = FINDNOCASE("XYZ", IN$);

      PRINT("XYZ was found starting at position %d in %s\n",

      START_LOC, IN$);

    }

If IN$ was set equal to "Hello, World!" then START_LOC would be 0 since "XYZ" can not be found. If IN$ was equal to "CPE1704XYZXYZ", then START_LOC would be equal to 8.

Version:

SIMPL+ Version 3.03.00 or later

CUZ 3.137 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
FindNoCase

CHANGE FINDNOCASE FindNoCase INTEGER PRINT STRING STRING_INPUT


Gather

# Gather

Name:

Gather

Syntax:

    STRING Gather(STRING Delimiter, STRING SourceString [INTEGER TimeOut]);

Description:

Concatenates the data from SourceString and issues it on the return string when the specified delimiter has been reached. At that time, the data will be removed from SourceString. Note that when Gather is executed, if SourceString does not include the Delimiter, then the equivalent of a PROCESSLOGIC is performed. When the system returns to the Gather, it will once again check for the proper delimiter. In effect, a section of code (a CHANGE statement, for example) is held up at the Gather until the proper data is received.

The optional Timeout parameter will provide a way for the function to transfer control back to the module when the specified time allows. If the Timeout parameter is specified, then the length of the return string should be checked to determine if a Timeout has occurred (length = 0).

Parameters:

Delimter is a string containing the terminating sequence of characters in the desired string.

SourceString is the string from which to remove the sequence of characters ending in the desired sequence.

Timeout is an integer specifying the timeout period in 1/100ths of a second.

NOTE:  It makes sense only to use Gather with STRING_INPUT or BUFFER_INPUT types.

Return Value:

The returned string includes concatenated data from SOURCESTRING and  the STRING DELIMITER.

Example:

    BUFFER_INPUT COM$[100];

    DIGITAL_INPUT trig;

    STRING IN$[100];

    PUSH trig

    {

      IN$ = GATHER("\n", COM$);

      PRINT("The value of IN$ is %s\n", IN$);

    }

In this example, the event is started when TRIG goes high. When data comes into COM$, the GATHER statement is evaluated. The PRINT statement is never reached until the delimiter \n (CRLF) is found. When the delimiter is found, then the string will be printed. Note that the GATHERed string will have the \n on it.

Example:

    BUFFER_INPUT COM$[100];

    DIGITAL_INPUT trig;

    STRING IN$[100];

    CHANGE COM$

    {

      IN$ = GATHER("\n", COM$);

      PRINT("The value of IN$ is %s\n", IN$);

    }

If, in the first event, COM$ contains the string "Hello", the event will wait in the GATHER. When the COM$ changes again to contain " World!\n", the event will immediately resume after the GATHER. The CHANGE COM$ event will only be called once in this case. In the X-Generation Control Systems, the CHANGE event would be called both times.

In the 2-Series Control System processors, a GATHER that is waiting for data will use up the next changes in the BUFFER_INPUT until the terminating character is encountered. That is, any CHANGE event handler for the BUFFER_INPUT will not be called.

Version:

SIMPL+ Version 3.03.00 or later

CUZ3.154 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
GATHER
Gather

BUFFER_INPUT CHANGE DIGITAL_INPUT GATHER Gather INTEGER PRINT PROCESSLOGIC PUSH STRING STRING_INPUT


GetC

# GetC

Name:

GetC

Syntax:

    INTEGER GetC(BUFFER_INPUT SOURCE);

Description:

Returns the value at position 1 of SOURCE string and shifts the rest of the buffer up by one. In this way, values may be picked out of a buffer for processing.

Parameters:

SOURCE is typically from a BUFFER_INPUT statement. It may be defined as a STRING or STRING_INPUT, but since GETC removes characters from SOURCE, the result is destructive to the source string.

Return Value:

An INTEGER containing a single character from position 1 of the buffer.

If there are no characters in the buffer for GETC to retrieve, then the value of 65535 is returned.

Example:

In this example, a buffer input is read until the character "A" is retrieved.

    BUFFER_INPUT IN$[100];

    INTEGER INCHAR;

    CHANGE IN$

    {

      INCHAR = 0;

      WHILE(INCHAR \<\> 'A')

        INCHAR = GETC(IN$);

      // continue processing.

    }

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
GETC
GetC

BUFFER_INPUT CHANGE GETC GetC INTEGER STRING STRING_INPUT WHILE


GatherAsync

# GatherAsync

Name:

GatherAsync

Syntax:

    [SIGNED_INTEGER] GatherAsync (STRING Delimiter, BUFFER_INPUT Input, GatherEventHandler EventHandler, [INTEGER Timeout]);

Description:

Receives BUFFER_INPUT data and flags it as waiting for a gather operation. When new data comes in from the logic engine, the match criteria will be evaluated.  If the condition is met,  i.e. specific sequence of characters is received, a thread will be triggered to invoke the  callback function, thus eliminating the need for a separate thread waiting on each input, as each threads will only be active when there is work to be done.

If the Timeout parameter is specified and the match condition has not been met before this time expires, the callback function is invoked with a result code of timeout.

Parameters:

Delimiter is a specific sequence of characters that marks the end of the desired data

Input is a BUFFER_INPUT variable that will receive data coming into the SIMPL+ module.

EventHandler is the callback function which is invoked when the Delimiter is found

Timeout is an optional INTEGER parameter which specifies the timeout period (n 1/100ths of a second.) after which the callback function will be called and the result code in the [GatherEventArgs] parameter will be set to -1.

Return Value:

Returned value provides information about the status of the gather operation, as follows:

|              |                                                |
|--------------|------------------------------------------------|
| Return Value | Description                                    |
| 0            | Success                                        |
| \<0          | Error occurred                                 |
| -1           | Problem with one of the parameters             |
| 1            | Success, but replacing previously set criteria |

Example:

DIGITAL_INPUT ByDelimiter;

PUSH ByDelimiter

{

GatherAsync(“\n”, MyInput, MyGatherCallback);

}

In this example, the event is triggered when the DIGITAL_INPUT ByDelimiter goes high. Data coming into MyInput is gathered until finding the delimiter '\n'.  After the delimiter is found,  MyGatherCallback is executed with the gathered data (including the delimiter) as an argument.

Version:

SIMPL+ Version 4.04.01 or later required

  [GatherEventArgs]: GatherEventArgs.md

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherAsync


GatherAsyncByLength

# GatherAsyncByLength

Name:

GatherAsyncByLength

Syntax:

     [SIGNED_INTEGER] GatherAsyncByLength (INTEGER NumCharsToMatch, BUFFER_INPUT input, GatherEventHandler EventHandler, [INTEGER Timeout]);

Description:

Receives BUFFER_INPUT data and flags it as waiting for a gather operation. When new data comes in from the logic engine, the match criteria will be evaluated.  If the condition is met,  i.e. number of bytes specified in INTEGER NumCharsToMatch is received, a thread will be triggered to invoke the callback function, thus eliminating the need for a separate thread waiting on each input, as each threads will only be active when there is work to be done.

If the optional Timeout parameter is specified and the match condition has not been met before this time expires, the callback function is invoked with a result code of timeout.

Parameters:

NumCharsToMatch is an integer specifying the number of desired characters before executing the callback function

Input is a BUFFER_INPUT variable that will receive data coming into the SIMPL+ module.

EventHandler is the callback function which is invoked when the Delimiter is found

Timeout is an optional integer parameter which specifies the timeout period (n 1/100ths of a second.) after which the callback function will be called and the result code in the GatherEventArgs parameter will be set to -1.

Return Value:

Returned value provides information about the status of the gather operation, as follows:

|              |                                                |
|--------------|------------------------------------------------|
| Return Value | Description                                    |
| 0            | Success                                        |
| \<0          | Error occurred                                 |
| -1           | Problem with one of the parameters             |
| 1            | Success, but replacing previously set criteria |

Example:

    DIGITAL_INPUT ByLength;

    PUSH ByLength

{

GatherAsyncByLength(40, MyInput, MyGatherByLengthCallback);

}

In this example, the event is triggered when the DIGITAL_INPUT ByLength goes high. Data coming into MyInput is gathered until the number of character reaches 40 and then  MyGatherCallback is executed with the gathered data as an argument.

Version:

SIMPL+ Version 4.04.01 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherAsyncByLength


GatherByLength (Part 1)

# GatherByLength

Name:

GatherByLength

Syntax:

     STRING GatherByLength(INTEGER NumBytes, STRING SourceString [INTEGER Timeout]);

Description:

Concatenates the data from SourceString and issues it on the return string when the specified number of bytes have been reached. At that time, the data will be removed from SourceString. Note that when GatherByLength is executed, if SourceString does not include the specified number of bytes, then the equivalent of a PROCESSLOGIC is performed. When the system returns to the GatherByLength, it will once again check for the specified number of bytes (INTEGER NumBytes). In effect, a section of code (a CHANGE statement, for example) is held up at the GatherByLength until the specified NumBytes  is received.

The optional Timeout parameter will provide a way for the function to transfer control back to the module when the specified time allows. If the Timeout parameter is specified, then the length of the return string should be checked to determine if a Timeout has occurred (length = 0).

Parameters:

NumBytes is an integer specifying the number of characters to be removed from the SourceString.

SourceString is the string from which to remove the sequence of characters ending in the desired sequence.

Timeout is an integer specifying the timeout period in 1/100ths of a second.

NOTE:  It makes sense only to use GatherByLength with STRING_INPUT or BUFFER_INPUT types.

Return Value:

The length of the returned string is the NumBytes specified.

Example:

    BUFFER_INPUT COM$[100];

    DIGITAL_INPUT trig;

    STRING IN$[100];

    PUSH trig

    {

      IN$ = GATHERBYLENGTH(2, COM$);

      PRINT("The value of IN$ is %s\n", IN$);

    }

In this example, the event is started when TRIG goes high. When data comes into COM$, the GatherByLength statement is evaluated. The PRINT statement is never reached until the number of bytes, NumBytes, is obtained. When the total number of bytes specified is obtained, then the string will be printed.

Example:

    BUFFER_INPUT COM$[100];

    DIGITAL_INPUT trig;

    STRING IN$[100];

    CHANGE COM$

    {

      IN$ = GATHER(2, COM$);

      PRINT("The value of IN$ is %s\n", IN$);

    }

If, in the first event, COM$ contains the string "Hello", the event will wait in the GATHERBYLENGTH. When the COM$ changes again to contain " World!\n", the event will immediately resume after the GATHERBYLENGTH. The CHANGE COM$ event will only be called once in this case.

In the 2-Series Control System processors, a GATHERBYLENGTH that is waiting for data will use up the next changes in the BUFFER_INPUT until the number of bytes is obtained. That is, any CHANGE event handler for the BUFFER_INPUT will not be called.

Example:

#DEFINE_CONSTANT GATHERBYLENGTH_TIMEOUT 200 // 2 second timeout

BUFFER_INPUT MyLengthString[1000];

CHANGE MyDelimitedString

{

   STRING LocalString[256];

   While (1)

   {

     LocalString = GatherByLength(2, MyDelimitedString, GATHER_TIMEOUT);

     If (Len(LocalString) = 0) // timeout occurred

     {

       ClearBuffer(MyDelimitedString);

       Print("Timeout occurred in Delimited string. \n");

       Break;

     }

     // code to work with received string

   }

 }

 CHANGE MyLengthString

 {

   STRING LocalString[256];

   While (1)

   {

     LocalString = GatherByLength(20, MyLengthString, GATHER_TIMEOUT);

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherByLength
GatherByLength

BUFFER_INPUT CHANGE ClearBuffer DEFINE_CONSTANT DIGITAL_INPUT GATHER GATHERBYLENGTH GatherByLength INTEGER If Len PRINT PROCESSLOGIC PUSH Part Print STRING STRING_INPUT While


GatherByLength (Part 2)

     If (Len(LocalString) = 0) // timeout occurred

     {

       ClearBuffer(MyLengthString);

       Print("Timeout occurred in Length string. \n");

       Break;

     }

     // code to work with received string

   }

 }

In this example, GatherByLength would continue to remove the specified number of bytes in MyLengthString until it was empty, which would cause a timeout.

Version:

SIMPL+ Version 3.03.00 or later

CUZ3.154 or later required

ClearBuffer GatherByLength If Len Part Print

Example:

#DEFINE_CONSTANT GATHERBYLENGTH_TIMEOUT 200 // 2 second timeout

BUFFER_INPUT MyLengthString[1000];

CHANGE MyDelimitedString

{

   STRING LocalString[256];

   While (1)

   {

     LocalString = GatherByLength(2, MyDelimitedString, GATHER_TIMEOUT);

     If (Len(LocalString) = 0) // timeout occurred

     {

       ClearBuffer(MyDelimitedString);

       Print("Timeout occurred in Delimited string. \n");

       Break;

     }

     // code to work with received string

   }

 }

 CHANGE MyLengthString

 {

   STRING LocalString[256];

   While (1)

   {

     LocalString = GatherByLength(20, MyLengthString, GATHER_TIMEOUT);


GatherByLengthWithDest

# GatherByLengthWithDest

Name:

GatherByLengthWithDest

Syntax:

    [SIGNED INTEGER] GatherByLengthWithDest(INTEGER NumCharsToMatch, BUFFER_INPUT Input, STRING Destination [,INTEGER Timeout]);

Description:

Concatenates the data from the BUFFER INPUT string into the destination string parameter till the specified number of characters has been reached.  In effect, GatherByLengthWithDest is a version of the traditional [GatherByLength] function that holds the result of the gather operation in the destination string parameter, thus improving the operational speed of GatherByLengthWithDest over the speed of the [GatherByLength] function.

Note that similarly to the traditional [GatherByLength] function, GatherByLengthWithDest is a blocking operation i.e. the thread will stop executing until the gather condition is satisfied or the optional timeout expires.

Parameters:

NumCharsToMatch is an integer specifying the number of desired characters.

Input is a BUFFER_INPUT variable that will receive data coming into the SIMPL+ module.

Destination is the destination string which will hold the result of the gather operation.

Timeout is an optional INTEGER parameter that allows the thread to continue to execute if the gather conditions are not met within the specified timeout period (in 1/100ths of a second.).

Return Values:

|  |  |
|----|----|
| Return Value | Description |
| 0 | Success |
| \<0 | Error occurred |
| -1 | Timeout occurred |
| -2 | Resource conflict.  Two threads are trying to access the same BUFFER_INPUT at the same time. |

Example:

    BUFFER_INPUT MyInput[256];

    DIGITAL_INPUT trig;

    STRING dest[80];

PUSH trig

{

   Signed_Integer Status;

   Status = GatherByLengthWithDest(24, MyInput, dest);

   PRINT ("The Value of dest is %s\n", dest);

     }

In this example, the event is triggered when the DIGITAL_INPUT trig goes high. Data coming into MyInput is gathered until the specified number of characters has been reached.  After that,  the destination string will be printed.

Version:

SIMPL+ Version 4.05.01 or later

  [GatherByLength]: GatherByLength.md

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherByLengthWithDest

BUFFER_INPUT DIGITAL_INPUT GatherByLength GatherByLengthWithDest INTEGER PRINT PUSH STRING


GatherEventArgs

# GatherEventArgs

Name:

GatherEventArgs

Description:

GatherEventArgs is a structure which is used to hold data about the gather operation and pass that data to the [GatherEventHandler].

GatherEventArgs has the following format:

STRUCTURE GatherEventArgs

{

STRING RxString;

SIGNED_INTEGER Results;

BUFFER_INPUT Input;

}

Field/Members:

RxString is the string resulting from the [GatherAsync] or [GatherAsyncByLength].  If a delimiter is specified in the [GatherAsync] call, then the delimiter is included in the string.

Results is the an integer representing the status of the gather operation. Possible values are:

              0:  Success

             -1: Timeout occurred.

Input is the buffer input associated with the [GatherAsync] or [GatherAsyncByLength]. This buffer input is used by the callback in the [RearmGatherAsync] call.

Example:

    callback GatherEventHandler MyGatherCallback(GatherEventArgs Args)

{

if (Args.RESULTS = 0)

{

Print(" Received Message: %s", Args.RXSTRING);

}

else

Print("Timeout in GatherAsync\n");

}

In this example, the GatherEventArgs structure is passed as an argument of [GatherEventHandler]. The result of the gather operation Args.RESULTS is evaluated and the first PRINT statement is executed to print the string Args.RXSTRING. In case of a timeout (Args.RESULTS = -1), the second PRINT statement is executed.

Version:

SIMPL+ Version 4.04.01 or later required

  [GatherEventHandler]: GatherEventHandler.md
  [GatherAsync]: GatherAsync.md
  [GatherAsyncByLength]: GatherAsyncByLength.md
  [RearmGatherAsync]: RearmGatherAsync.md

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherEventArgs

BUFFER_INPUT GatherAsync GatherAsyncByLength GatherEventArgs GatherEventHandler MyGatherCallback PRINT Print RearmGatherAsync SIGNED_INTEGER STRING STRUCTURE

GatherEventHandler GatherAsync GatherAsyncByLength RearmGatherAsync


GatherEventHandler

# GatherEventHandler

Name:

GatherEventHandler

Syntax:

    callback GatherEventHandler myCallBack(GatherEventArgs args);

Description:

GatherEventHandler is a callback function that is supplied as an argument to [GatherAsync] or [GatherAsyncByLength], such that the GatherEventHandler is invoked when the match criteria in [GatherAsync] or [GatherAsyncByLength] are met.

Parameters:

Args is a structure of type [GatherEventArgs] containing data from the gather operation..

Example:

    callback GatherEventHandler MyGatherCallback(GatherEventArgs Args)

{

if (Args.RESULTS = 0)

{

Print("Got Message: %s", Args.RXSTRING);

RearmGatherAsync(Args.INPUT);

}

else

Print("Got a timeout in GatherAsync\n");

}

Version:

SIMPL+ Version 4.04.01 or later required

  [GatherAsync]: GatherAsync.md
  [GatherAsyncByLength]: GatherAsyncByLength.md
  [GatherEventArgs]: GatherEventArgs.md

Language Constructs & Functions
String Parsing & Manipulation Functions
GatherEventHandler

GatherAsync GatherAsyncByLength GatherEventArgs GatherEventHandler MyGatherCallback Print RearmGatherAsync


Left

# Left

Name:

Left

Syntax:

    STRING Left(STRING SOURCE, INTEGER NUM);

Description:

Takes the leftmost NUM characters of SOURCE and returns them in an output string.

Parameters:

SOURCE is a STRING containing the source string.

NUM is an INTEGER that tells LEFT how many characters to use in the computation.

Return Value:

A string representing the leftmost NUM characters of SOURCE. If NUM is greater than the number of characters in SOURCE, then the return is identical to SOURCE.

Example:

    STRING_INPUT Var$[100];

    STRING Temp$[100];

    CHANGE Var$

    {

      Temp$ = LEFT(Var$, 5);

      PRINT("Left most 5 characters of %s are %s\n", Var$, Temp$);

    }

In this example, if  Var$ is "abcdefghijk",  Temp$ will contain "abcde".

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
LEFT
Left

CHANGE INTEGER LEFT Left PRINT STRING STRING_INPUT


Len

# Len

Name:

Len

Syntax:

    INTEGER Len(STRING SOURCE);

Description:

Returns the actual length of the string, not the declared maximum length.

Parameters:

SOURCE is a string whose length is to be determined.

Return Value:

A value from 0 - 65535, which gives the number of characters in the string. An empty string returns a length of 0.

Example:

    STRING_INPUT IN$[100];

    INTEGER Temp;

    CHANGE IN$

    {

      Temp = LEN(IN$);

      PRINT("The Length of %s is %d\n", IN$, Temp);

    }

In this example, if IN$ is equal to "This is a test" then Temp will contain the integer 14.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
LEN
Len

CHANGE INTEGER LEN Len PRINT STRING STRING_INPUT


Lower

# Lower

Name:

Lower

Syntax:

    STRING Lower(STRING SOURCE);

Description:

Takes a source string and converts characters with the values A-Z (uppercase) to a-z (lowercase).

Parameters:

SOURCE is a string to be converted to lowercase. SOURCE is not modified, unless it is also used as the return value, e.g., S$=LOWER(S$);

Return Value:

A STRING containing the lowercase version of SOURCE. Characters that do not fall into the range A-Z are not modified and will stay as specified. You can use the same variable for both the argument and return. e.g., s$=lower(s$);

Example:

    STRING_INPUT IN$[100];

    STRING LOWER$[100];

    CHANGE IN$

    {

      LOWER$ = LOWER(IN$);

      PRINT("Lowercase version of %s is %s\n",IN$, LOWER$);

    }

In this example, if IN$ contains "This is a Test123!", then LOWER$ will contain "this is a test123!".

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
LOWER
Lower

CHANGE LOWER Lower PRINT STRING STRING_INPUT


Mid

# Mid

Name:

Mid

Syntax:

    STRING Mid(STRING SOURCE, INTEGER START, INTEGER NUM);

Description:

Returns a string NUM characters long from SOURCE, starting at position START.

Parameters:

SOURCE is a STRING containing the input string.

START is an INTEGER telling MID at which character position in SOURCE to start. The first character of SOURCE is considered 1.

NUM is an INTEGER telling MID how many characters to use from SOURCE.

Return Value:

A string NUM characters long starting at START.

If START is greater than the length of SOURCE, an empty STRING is returned.

If NUM is greater than the total number of characters that can be retrieved starting from START, only the remaining characters in SOURCE will be pulled. For example, MID("ABCD", 2, 10) would return a STRING containing BCD.

Example:

    STRING_INPUT Var$[100];

    STRING Temp$[100];

    CHANGE Var$

    {

      Temp$ = MID(Var$, 2, 5);

      PRINT("String starting at position 2 for 5 characters is %s\n",

            Temp$);

    }

In this example, if Var$ contains "abcdefghijklmnop", then Temp$ will contain "bcdef".

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
MID
Mid

CHANGE INTEGER MID Mid PRINT STRING STRING_INPUT


String Parsing and Manipulation Functions Overview (Part 1)

# String Parsing and Manipulation Functions Overview

String parsing and manipulation functions are used where the contents of string variables need to be examined or modified.

Functions Manipulation Overview Parsing Part String and


String Parsing and Manipulation Functions Overview (Part 2)

| Function               | Description                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ClearBuffer            | Deletes the contents of the specified buffer.                                                                                |
| CompareStrings         | Performs a case-sensitive comparison of two strings.                                                                                |
| CompareStringsNoCase   | Performs a case-insensitive comparison of two strings.                                                                                |
| Find                   | Finds the position in SOURCE_STRING where MATCH_STRING first occurs. Search is case sensitive.                                                                                |
| FindNoCase             | Finds the position in SOURCE_STRING where MATCH_STRING first occurs. The search is case insensitive.                                                                                |
| Gather                 | Concatenates the data from SOURCESTRING and issues it on the return string when the specified delimiter has been reached.                                                                                |
| GatherAsync            | Concatenates the data from the BUFFER INPUT string into the destination string parameter until specific sequence of characters is received                                                                                |
| GatherAsyncByLength    | Concatenates the data from the BUFFER INPUT string until the number of bytes specified in NumCharsToMatch is received,                                                                                |
| GatherByLength         | Concatenates the data from SourceString and issues it on the return string when the specified number of bytes have been reached.                                                                                |
| GatherByLengthWithDest | Concatenates the data from the BUFFER INPUT string into the destination string parameter till the specified number of characters has been reached.                                                                                |
| GetEncoding            | 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. |
| Left                   | Takes the leftmost NUM characters of SOURCE and returns them in an output string.                                                                                |
| Len                    | Returns the actual length of the string, not the declared maximum length.                                                                                |
| Lower                  | Takes a source string and converts characters with the values A-Z (uppercase) to a-z (lowercase).                                                                                |
| Mid                    | Returns a string NUM characters long from SOURCE, starting at position START.                                                                                |
| RearmGatherAsync       | Resets the Gather trigger to the criteria used in the previous match                                                                                |
| Remove                 | Begins searching a string <source> for the <delimiter> at the specified position, then removes all characters from the beginning of the string <source> up to and including the delimiter.                                                                                |
| RemoveByLength         | Removes all characters from the beginning of the SOURCESTRING up to the NumBytes specified and returns a string containing the number of bytes removed                                                                                |
| RemoveGatherAsync      | Removes the specified the BUFFER INPUT serial data from the gather operation.                                                                                |
| ResizeString           | Changes the allocated size of the string to NewSize bytes.                                                                                |
| ReverseFind            | Finds the position in SOURCE_STRING where MATCH_STRING last occurs. Case sensitive.                                                                                |
| ReverseFindNoCase      | Finds the position in SOURCE_STRING where MATCH_STRING last occurs. Case insensitive.                                                                                |
| Right                  | Takes the rightmost NUM characters of SOURCE and returns them in an output string.                                                                                |
| SetEncoding            | Converts the encoding of a UTF16 string to ASCII.                                                                                |
| SetString              | Overwrites the bytes in DESTINATION with the bytes in SOURCE starting at POSITION in the DESTINATION string.                                                                                |
| ToASCII                | Converts the encoding of a UTF16 string to ASCII.                                                                                |
| ToUTF16                | Converts the encoding of the string to UTF16.                                                                                |
| Upper                  | Takes a source string and converts characters with the values a-z (lowercase) to A-Z (uppercase).                                                                                |


Remove

# Remove

Name:

Remove

Syntax:

    STRING Remove(STRING DELIMITER, STRING SOURCESTRING, [INTEGER STARTPOS]);

Description:

Begins searching a string \<SOURCESTRING\> for the \<DELIMITER\> at the specified starting position \<STARTPOS\>, then removes all characters from the beginning of the string \<SOURCESTRING\> up to and including the delimiter. Returns a string containing all of the removed characters.

Parameters:

DELIMITER is a string containing the terminating sequence of characters in the desired string.

SOURCESTRING is the string the Remove function is performed on. Characters up to and including the DELIMITER are removed and returned as a string.

STARTPOS is the starting position in the \<SOURCESTRING\> to start searching for the \<DELIMITER\>.  It is 1 based. The first byte of \<SOURCESTRING\> is at position 1.

Return Value:

A string including the delimiter.

Example:

    BUFFER_INPUT SOURCE$[50];

    STRING OUTPUT$[50];

    CHANGE SOURCE$

    {

      OUTPUT$ = REMOVE("abc", SOURCE$);

    }

In this example, if SOURCE$ were "testabc123", then OUTPUT$ would be "testabc" and SOURCE$ would contain "123".

    BUFFER_INPUT SOURCE$[50];

    STRING OUTPUT$[50];

    CHANGE SOURCE$

    {

      OUTPUT$ = REMOVE("abc", SOURCE$, 6);

    }

If SOURCE$ were "testabcabc123", then OUTPUT$ would be "testabcabc" and SOURCE$ would contain "123".

Version:

SIMPL+ Version 3.02.02 or later

CUZ 3.137 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
REMOVE
Remove

BUFFER_INPUT CHANGE INTEGER REMOVE Remove STRING


REVERSEFIND

# REVERSEFIND

Name:

ReverseFind

Syntax:

    INTEGER ReverseFind(STRING MATCH_STRING, STRING SOURCE_STRING

                        [, INTEGER START_POSITION]);

Description:

Finds the position in SOURCE_STRING where MATCH_STRING last occurs.  The search is case-sensitive.

Parameters:

MATCH_STRING is a STRING containing the searched for data.

SOURCE_STRING is a STRING containing the data to be searched.

START_POSITION is an INTEGER which tells REVERSEFIND at what character in the string to start the search, and is 1 based. If it is not specified, it defaults to the end of the string.

Return Value:

The index of where MATCH_STRING last occurs (going right to left) in SOURCE_STRING. If the data can not be found, or POSITION exceeds the length of the SOURCE_STRING then 0 is returned. The index is 1 based.

Example:

    STRING_INPUT IN$[100];

    INTEGER START_LOC;

    CHANGE IN$

    {

      START_LOC = REVERSEFIND("XYZ", IN$);

      PRINT("last XYZ occurrence was found at position %d in %s\n", START_LOC, IN$);

    }

If IN$ was set equal to "Hello, World!" then START_LOC would be 0 since "XYZ" can not be found. If IN$ was equal to "CPE1704XYZXYZ", then START_LOC would be equal to 11.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
REVERSEFIND

CHANGE INTEGER PRINT REVERSEFIND ReverseFind STRING STRING_INPUT


Right

# Right

Name:

Right

Syntax:

    STRING Right(STRING SOURCE, INTEGER NUM);

Description:

Takes the rightmost NUM characters of SOURCE and returns them in an output string.

Parameters:

SOURCE is a STRING containing the source string.

NUM is an INTEGER that tells RIGHT how many characters to use in the computation.

Return Value:

A string representing the rightmost NUM characters of SOURCE. If NUM is greater than the number of characters in SOURCE, then the return is identical to SOURCE.

Example:

    STRING_INPUT Var$[100]

    STRING Temp$[100];

    CHANGE Var$

    {

      Temp$ = RIGHT(Var$, 5);

      PRINT("Right most 5 characters of %s are %s\n", Var$, Temp$);

    }

In this example, if Var$ contains "abcdefghijk", then Temp$ contains "ghijk".

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
RIGHT
Right

CHANGE INTEGER PRINT RIGHT Right STRING STRING_INPUT


RearmGatherAsync

# RearmGatherAsync

Name:

RearmGatherAsync

Syntax:

    SIGNED_INTEGER RearmGatherAsync (BUFFER_INPUT Input);

Description:

Resets the Gather trigger to the criteria used in the previous match. When criteria in [GatherAsync] or [GatherAsyncByLength]. is met,  the callback function [GatherEventHandler] will be triggered once. If a further match is desired, the RearmGatherAsync function has to be called as the end line of [GatherEventHandler].

Parameters:

Input is the buffer input associated with the [GatherAsync] or [GatherAsyncByLength].

Return Value:

Returned value provides information about the status of the gather operation, as follows:

|  |  |
|----|----|
| Return Value | Description |
| 0 | Success |
| \<0 | Error occurred |
| -1 | There was no previous gather operation for the specified BUFFER_INPUT |

Example:

    callback GatherEventHandler MyGatherCallback(GatherEventArgs Args)

{

if (Args.RESULTS = 0)

{

RearmGatherAsync(Args.INPUT);

}

else

...

}

In this example, the callback function, the RearmGatherAsync is called so to utilize the same gather criteria that was used in the previous gather operation.

Version:

SIMPL+ Version 4.04.01 or later required

  [GatherAsync]: GatherAsync.md
  [GatherAsyncByLength]: GatherAsyncByLength.md
  [GatherEventHandler]: GatherEventHandler.md

Language Constructs & Functions
String Parsing & Manipulation Functions
RearmGatherAsync

BUFFER_INPUT GatherAsync GatherAsyncByLength GatherEventHandler MyGatherCallback RearmGatherAsync SIGNED_INTEGER


RemoveByLength

# RemoveByLength

Name:

RemoveByLength

Syntax:

    STRING RemoveByLength(INTEGER NUMBYTES, STRING SOURCESTRING);

Description:

Removes all characters from the beginning of the string \<SOURCESTRING\> up to the NumBytes specified. Returns a string containing the number of bytes removed.

Parameters:

SOURCESTRING is the string the RemoveByLength function is performed on. Characters up to the NumBytes are removed and returned as a string.

NUMBYTES is an integer specifying the number of characters to be removed from a SOURCESTRING. The bytes are removed starting at the first character (position 1) in the \<SOURCESTRING)

Return Value:

If the length of \<SOURCESTRING\> is 0, a string of length 0 is returned.

If the length of \<SOURCESTRING\> is \<  \<NUMBYTES\>, then \<SOURCESTRING\> is not modified and a string of 0 length will be returned.

If the length of \<SOURCESTRING\> is \>= \<NUMBYTES\>, then the first \<NUMBYTES\> of \<SOURCESTRING\> will be returned.  \<SOURECESTRING\> is left with the rightmost LEN(\<SOURCESTRING\>)-\<NUMBYTES\> characters.

Example:

    BUFFER_INPUT SOURCE$[50];

    STRING OUTPUT$[50];

    CHANGE SOURCE$

    {

      OUTPUT$ = REMOVEBYLENGTH(2, SOURCE$);

    }

In this example, if SOURCE$ were "testabc123", then OUTPUT$ would be "te" and SOURCE$ would contain "stabc123".

Version:

SIMPL+ Version 3.02.05 or later

CUZ 3.154 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
RemoveByLength

BUFFER_INPUT CHANGE INTEGER LEN REMOVEBYLENGTH RemoveByLength STRING


RemoveGatherAsync

# RemoveGatherAsync

Name:

RemoveGatherAsync

Syntax:

    SIGNED_INTEGER RemoveGatherAsync (BUFFER_INPUT Input);

Description:

Removes/un-registers the specified BUFFER_INPUT serial data from the gather operation.

Parameters:

Input is the BUFFER_INPUT associated with [GatherAsync] or [GatherAsyncByLength].

Return Value:

Returned value provides information about the status of the gather operation, as follows:

|  |  |
|----|----|
| Return Value | Description |
| 0 | Success |
| \<0 | Error occurred |
| -1 | There was no previous gather operation for the specified BUFFER_INPUT |

Example:

    DIGITAL_INPUT StopGather;

    BUFFER_INPUT MyInput[256];

PUSH StopGather

{

RemoveGatherAsync(MyInput);

}

In this example, when DIGITAL_INPUT StopGather goes high the BUFFER_INPUT MyInput is removed from the Gather operation.

Version:

SIMPL+ Version 4.04.01 or later

  [GatherAsync]: GatherAsync.md
  [GatherAsyncByLength]: GatherAsyncByLength.md

Language Constructs & Functions
String Parsing & Manipulation Functions
RemoveGatherAsync


ResizeString

# ResizeString

Name:

ResizeString

Syntax:

    SIGNED_INTEGER ResizeString (STRING StringVar, INTEGER NewSize);

Description:

Changes the allocated size of the string to NewSize bytes.

NOTE: To use this function, the [#ENABLE_DYNAMIC] compiler directive must be present in the SIMPL+ module and the variable must be declared as [DYNAMIC].

Parameters:

StringVar is the string variable that needs a change in the allocated size. NewSize indicates the new number of bytes in the string.

Return Value:

|          |                                  |
|----------|----------------------------------|
| Status   | Definition                       |
| 0        | Success                          |
| 0x8001   | Generic Error                    |
| 0x8002   | Error – Max Resize limit reached |
| 0x8004\* | Error – Element is not dynamic   |
| 0x8008   | Warning – Truncation will occur  |
| 0x8010   | Error – Out of memory            |
| 0x8020   | Error – Out of memory            |
| 0x8040   | Error – Out of memory            |

\* This error indicates that the #ENABLE_DYNAMIC compiler directive is missing from the SIMPL+ module and/or that the variable has not been declared as DYNAMIC.

NOTE:  The status might contain an error and a warning returned together. For example, if a string is resized from 20 to 10 characters, a truncation warning will result. However, if the system is out of memory, the resize cannot be completed. In this scenario, the returned status will be 0x8008 | 0x8010,  or 0x8018.

Example:

    DYNAMIC STRING MyString[10];

    Function main()

    {

         SIGNED_INTEGER Status;

         Status = ResizeString(MyString, 200);

         If (status != 0)

              Print("Error occurred in resizing string MyString\n")

    }

Version:

2 Series only

X Gen not supported

  [#ENABLE_DYNAMIC]: javascript:void(0);
  [DYNAMIC]: javascript:void(0);

Language Constructs & Functions
String Parsing & Manipulation Functions
ResizeString

ENABLE_DYNAMIC INTEGER If Print ResizeString SIGNED_INTEGER STRING


ReverseFindNoCase

# ReverseFindNoCase

Name:

ReverseFindNoCase

Syntax:

    INTEGER ReverseFindNoCase(STRING

                        [, INTEGER START_POSITION]);

Description:

Finds the position in SOURCE_STRING where

Parameters:

MATCH_STRING is a STRING containing the searched for data.

SOURCE_STRING is a STRING containing the data to be searched.

START_POSITION is an INTEGER which tells

Return Value:

The index of where MATCH_STRING last occurs (going right to left) in

Example:

    STRING_INPUT IN$[100];

    INTEGER START_LOC;

    CHANGE IN$

    {

      START_LOC =

      PRINT("last XYZ occurrence was found at position %d in %s\n", START_LOC, IN$);

    }

If IN$ was set equal to "Hello, World!" then START_LOC would be 0 since "XYZ" cannot be found. If IN$ was equal to "CPE1704XYZXYZ", then START_LOC would be equal to 11.

Version:

SIMPL+ Version 2.10.00 or later

CUZ 3.137 or later required

Language Constructs & Functions
String Parsing & Manipulation Functions
ReverseFindNoCase

CHANGE INTEGER PRINT ReverseFindNoCase STRING STRING_INPUT


SetString

# SetString

Name:

SetString

Syntax:

For X Generation: INTEGER SetString(STRING SOURCE, INTEGER POSITION,

                   STRING DESTINATION);

For 2-Series:    SIGNED_INTEGER SetString(STRING SOURCE,

                 INTEGER POSITION, STRING DESTINATION);

Description:

Overwrites the bytes in DESTINATION with the bytes in SOURCE starting at POSITION in the DESTINATION string. Performs an overwrite.

Parameters:

DESTINATION is a STRING containing the string to be modified.

POSITION is an INTEGER referencing the starting byte to write at in DESTINATION. 1 is the first byte of the string.

SOURCE is a STRING containing the string to use in the operation.

Return Value:

The new length or an error code, as defined below:

For the purposes of the explanation, a string has been declared STRING DESTINATION[MAX_LEN]. The string has a current length defined by LEN(DESTINATION).

e.g., If the specified position is beyond the declared length of the destination string:

If POSITION \> MAX_LEN, no operation is performed and -8 is returned.

e.g., If the entire source string can't be inserted without exceeding the length of the destination string:

If POSITION-1+LEN(SOURCE) \> MAX_LEN, the operation is performed, the string is truncated and -4 is returned.

e.g., If the position exceeds the current length of the destination:

If POSITION \> LEN(DESTINATION), the string is padded with spaces and -2 is returned.

e.g., If the source string will make the destination string longer:

If POSITION-1+LEN(SOURCE) \> LEN(DESTINATION), the string will be expanded to fit and -1 will be returned.

NOTE:  If more than one condition is met (typically -2 and -1 would be met at the same time), the codes are added together as the return value.

NOTE:  The subroutine knows the max length of the destination string.

If the operation meets none of the above conditions, the new length is returned.

The return code may be ignored (as in the example below).

Example:

    STRING DESTINATION$[100];

    DESTINATION$ = "Space XXXX To Fill";

    SETSTRING("ABCD", 7, DESTINATION$);

Would result in DESTINATION containing the string "Space ABCD To Fill". If the return code were used, it would contain 18 (the string length).

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
SETSTRING
SetString

INTEGER LEN SETSTRING SIGNED_INTEGER STRING SetString


Upper

# Upper

Name:

Upper

Syntax:

    STRING Upper(STRING SOURCE);

Description:

Takes a source string and converts characters with the values a-z (lowercase) to A-Z (uppercase).

 You can use the same variable for both the argument and return. e.g., s$=lower(s$);

Parameters:

SOURCE is a string to be converted to uppercase. SOURCE is not modified, unless it is also used as the return value, e.g., S$=UPPER(S$)

Return Value:

A STRING containing the uppercase version of SOURCE. Characters that do not fall into the range a-z are not modified and will stay as specified.

Example:

    STRING_INPUT IN$[100];

    STRING UPPER$[100];

    CHANGE IN$

    {

      UPPER$ = UPPER(IN$);

      PRINT("Uppercase version of %s is %s\n",IN$, UPPER$);

    }

In this example, if IN$ contains "Hello There 123!" then UPPER$ contains "HELLO THERE 123!".

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

Language Constructs & Functions
String Parsing & Manipulation Functions
UPPER
Upper

CHANGE PRINT STRING STRING_INPUT UPPER Upper


Delay

# Delay

Name:

Delay

Syntax:

    Delay(INTEGER TIME);

Description:

Forces a task switch and starts a timer for the hundredths of a second specified by TIME. The system continues with the statements after a delay when the delay time has expired.

See also: [Wait].

Parameters:

TIME is the number of hundredths of a second to delay. For example, 500 specifies a 5-second delay.

Return Value:

None.

Example:

    // A delay of 525 hundredths of a second or 5.25 seconds

    #define_constant MY_DELAY 525

    DELAY(MY_DELAY);

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

  [Wait]: ../Wait_Events/WAIT.md

Language Constructs & Functions
System Control
DELAY
Delay


System Control Overview

# System Control Overview

These constructs control system behavior and may change the resultant flow of the given SIMPL+ program.

Language Constructs & Functions
System Control
Overview
System Control Overview


ProcessLogic

# ProcessLogic

Name:

ProcessLogic

Syntax:

    ProcessLogic();

Description:

Forces a task switch away from the current SIMPL+ module, so that the SIMPL program can process the outputs of the SIMPL+ module. Refer to the discussion on [Task Switching].

Parameters:

None.

Return Value:

None.

Example:

    INTEGER X;

    ANALOG_OUTPUT I;

    FOR(X=0 TO 25)

    {

      I = X;

      PROCESSLOGIC();

    }

In this example, the analog output I is updated every pass through the loop. Logic dependent upon the analog value will see the new analog value every pass through the loop.

Version:

X Generation:  SIMPL v1.20.01 and later

2-Series:  SIMPL v2.01.05 and later

  [Task Switching]: ../../Task_Switching/Task_Switching_for_2-Series_Control_Systems.md

Language Constructs & Functions
System Control
PROCESSLOGIC
ProcessLogic

ANALOG_OUTPUT FOR INTEGER PROCESSLOGIC ProcessLogic Switching Task