Programs

Topic: DMD0232

Help File Version: 2.10.0.636

Programs

Programs are code-blocks that can be individually run as part of the current Do-more controller scan. Programs are the proper choice for typical ladder logic operations that involve timing, processing asynchronous instructions, handling ladder logic that takes multiple scans to complete, etc. A Program is required when Stage Programming instructions will be used.

Running a Program

The programmer controls when Programs are executed by using the Run Program (RUN) instruction.

If the Program contains Stage (SG) instructions, on the first scan where the Program will run, all of the Stage (SG) instructions will automatically be turned OFF, then the Initial Stage will be turned ON.

Stopping a Program

Once a Program has been started, it will run on every PLC scan until one of the following happens:

An Exit This Program (EXIT) instruction within the Program itself is executed.

Another Program or Task executes a Halt Program or Task (HALT) instruction that targets this Program.

The Project Browser -> Debug Code Block -> HALT Program or Task option is used to stop the Program.

Termination Scan Behavior

Termination behavior describes the actions that the Program code-block will perform on its termination scan.

All of the Output Coil (OUT) instructions will be turned OFF.

All of the Stage (SG) instructions will be turned OFF.

All Timers (except TMRAG - Global Accumulating Timer) will be reset.

All Counters (except UDCG Global Up / /Down Counter) will be reset.

All instructions with an edge-triggered input will have their edge inputs reset.

Refer to the Termination Behavior Help topic for more information about the termination scan and a for list of all the programming elements that have termination logic.

Program Structure Members

Each Program in a Do-more project has an associated structure that contains status information and control fields for the Program that are programmatically accessible. The values in the structure are updated each time scan that the Program runs. The syntax for using them is <program name>.<field name>.

.Running - a read-only Bit location that indicates whether the Program is currently running

is ON if the Program is running
is OFF if the Program is not running

.RanThisScan - a read-only Bit location that indicates whether the Program ran as part of the current controller scan

is ON if the Program ran on the current scan
is OFF if the Program did not run on the current scan

.Done - a read-only Bit location that shows whether the Program has completed

is ON if the Program has run to completion
is OFF if the Program is currently running or has never Run

.FirstScan - a read-only Bit location that indicates whether this is the Program's first scan after a PROGRAM -to- RUN transition

is ON if the Program is executing it's first scan
is OFF if the Program has completed it's first scan

.FirstRun - a read-only Bit location that indicates whether the Program has completed one full pass through all of it's ladder code after a PROGRAM -to- RUN transition. If the Program contains looping instructions (FOR / NEXT, WHILE / WEND, REPEAT / UNTIL, GOTO / LABEL) the Program's first run may take multiple controller scans to complete.

is ON if the Program is still executing it's first full pass
is OFF if the Program has completed it's first full pass or has never been run

.DoneThisScan - a read-only Bit location that indicates whether the Program has executed the final rung of ladder logic in the Program

is ON if the Program stopped on the current scan
is OFF if the Program did not stop execution on the current scan

.InstrSuspend - a read-only Bit location that indicates the Program is currently being suspended by a Suspend Program or Task (SUSPEND) instruction.

is ON if the Program is suspended by a SUSPEND instruction
is OFF if the Program is not suspended by a SUSPEND instruction

.DebugSuspend - a read-only Bit location that the Program is currently being suspended by a Debug View operation - a Program that is suspended will also have a yellow background in the Project Browser.

is ON if the Program is suspended by a debug operation
is OFF if the Program is suspended by a debug operation

.TimeSlice - a read-only, unsigned 32-bit location that contains the amount of time (in microseconds) per controller scan to allow Programs containing any looping instructions to run.

.ScanCounter - a read-only, signed 32-bit location that contains the number of controller scans during which the Program has run. This value is reset to 0 when the Program is first run and will retain the last value until the Program is stopped and set to run again.

.RunCounter - a read-only, signed 32-bit location that contains the number of times the Program has run to completion. This value is reset to 0 when the Program is first run and will retain the last value until the Program is stopped and set to run again. If there are no looping constructs (FOR / NEXT, WHILE / WEND, REPEAT / UNTIL, GOTO / LABEL) the .RunCounter value and the .ScanCounter value will be the same

Active Stages - contains 2 different representations of the Enabled / Disabled status of the Stages in the Program.

.S0_15 through .S112_127 - 8 consecutive read-only, unsigned 16-bit locations, each location contains the Enabled / Disabled status for 16 consecutive Stages
.S0 through .S127 - 128 consecutive read-only, bit locations that contain the Enabled / Disabled status for all of the Stages in the Program

Run Program (RUN) instruction

The Run Program (RUN) instruction is used to run a user-defined Program or a system Program.

This instruction does NOT cause the controller to immediately begin execution of the Program, rather it configures the Program to run when the controller gets to it as part of it's normal scan. If the Program exists later in the execution order the Program will begin execution on the same PLC scan. If the Program exists earlier in the execution order the Program will begin execution on the subsequent scan.

The gray triangle at the right end of an input leg indicates the input is Edge Triggered Each time the input logic transitions from OFF to ON this instruction will execute. With each execution, this instruction will run to completion even if the input logic transitions to OFF before the instruction completes..

The following fields will be displayed in the status display:

.RanThisScan - will be ON if the Program ran on the current scan and OFF if the Program did not run on the current scan

.Done - will be ON if the Program has run to completion and will be OFF if the Program is currently running or has never run

Stage Programming in Program Code-blocks

Each Program code-block can have up to 128 stages. For Example, $Main is a Program, so it can have up to 128 stages, named $Main.S0 through $Main.S127 (decimal). A separate Program called MonitorAlarms can also have up to 128 of it's own stages, named MonitorAlarms.S0 through MonitorAlarms.S127. Each Program’s stage bits are contained within that program’s structure memory.

A Program is required if any of the Stage Programming instructions are used.

Stage Programming Instructions:

Some instructions are classified as Fully Asynchronous which means the instruction is dependent on a shared device to complete the operation, and this operation can take more then one PLC scan. When the instruction is executed it will lock the device to gain exclusive use of that device while the instruction is being processed. When the instruction is completed it will unlock the device so that the device can be used by the next instruction that needs it. These instructions can be configured to "Jump to a Stage" when they are done, so if configured in this way, these instructions must be placed in a Program (not a Task).

Beyond using Programs to modularize a ladder logic program, and help with segmenting the ladder logic into functional blocks that can be enabled and./ or disabled, utilizing the Program related instructions can help tailor the Project's execution to better fit the application.

Using the Yield Program or Task (YIELD) Instruction

Suppose, for example, that the most pressing need is to minimize the scan time of the controller. If the Program has ladder logic that does not need to run every scan, one or more Yield Program or Task (YIELD) instructions can be embedded in the Program. YIELD instructions will cause the Program to suspend execution at that point in the Program, and return to processing to the next project element (this could be the next Program or the main ladder logic section). The next scan this Program is run, processing will begin when right after the YIELD instruction that was last executed. Refer to the following pseudo-code:

Program Start

Ladder Code < -- this rung is executed the 1st scan the Program is run

Yield

Ladder Code < -- this rung is executed the 2nd scan the Program is run

Yield

Ladder Code < -- this rung is executed the 3rd scan the Program is run

Program End

This process of segmenting the Program into subsections that will be run on subsequent executions allows the controller to process fewer instructions per scan, which keeps the scan time as low as possible. Of course it is the responsibility of the developer to decide where to place the YIELD instructions so that the application still functions and the scan time is minimized.

Managing Looping Instructions within Programs

Inside a Program you can use looping instructions (FOR / NEXT, WHILE / WEND, REPEAT / UNTIL, GOTO / LABEL) that will process the ladder logic instructions inside the loop as long as the input condition is TRUE. Using a loop in a Program brings with it the potential to cause the scan time to get really long, or if something goes really wrong, it can cause the CPU's watchdog timer to fire. So in order to prevent this from happening, each Program has a .TimeSlice value that defines the amount of processing time (in microseconds) to allow a Program to process looping instructions before it yields to other processes.

As discussed above, the Program's .TimeSlice value will be set to it's Initial TimeSlice value on a STOP mode -to- RUN mode change. Refer to the following pseudo-code:

Program Start

Ladder Code < -- this rung is executed the 1st scan the Program is run

While condition is true

Ladder Code < -- this rung is executed as long as the loop condition is met

Wend < -- if configured to do so, the Program always will yield at this point, and return here once the Program is running again

< -- on return, if While condition is TRUE, the while loop will be executed again

< -- on return, if While condition is FALSE, execution will move to the following rungs

Ladder Code < -- this rung is executed on the same scan that the While condition is false

Program End

Setting the .TimeSlice value at 0 effectively means the Program will make one pass through the loop each time the Program is allowed to run.

To allow the loop to run more than once per pass through the Program, set the .TimeSlice structure member to the number of micro-seconds to allow the Program to run, up to a maximum value of 65534 micro-seconds.

To allow the loop to complete in one scan, set the .TimeSlice structure member to the 65535 micro-seconds.

Using Restart Program or Task (RESTART)

Another way to further control the processing of a Program is through the Restart Program or Task (RESTART) instruction. If a Program containing one or more YIELD instructions has been allowed to run at least once so that the execution pointer - that is where the Program will begin executing when it is allowed to run again - is not at the beginning of the Program, you can use the Restart Program or Task (RESTART) instruction to reset the execution pointer (and the Program's flags) so that the next time the Program is allowed to run, it will begin at the first rung of the Program instead of at the point of the last YIELD instruction.

Program Start

Ladder Code < -- this rung is executed the 1st scan the Program is run

Yield

Ladder Code < -- this rung is executed the 2nd scan the Program is run

Yield

Restart Program or Task (RESTART) < -- Program was terminated and the execution pointer was reset to the first instruction in this Program, so the following two rungs were not processed.

Ladder Code

Program End

Note: The Halt Program or Task (HALT) instruction is used to stop the execution of a Program without setting it to restart on the next scan.

Using Exit This Program (EXIT)

Control of the processing of a Program can also be done internally to the Program through the optional EXIT This Program (EXIT) instruction. This instruction provides a way to have multiple exit points for a given Program.

Program Start

Ladder Code

If Condition 1 then Exit This Program

Ladder Code < -- if Condition 1 is met this rung is not executed

If Condition 2 then Exit This Program

Ladder Code < -- if Condition 2 is met this rung is not executed

Program End

Data View Display Formats

There are 4 variations of the Data View display of a Program, each with different amounts of data and / or different display orientations. These formats are for display purposes only, the Run Program variables cannot be edited when displayed using any of the formats.

Short Single Line: