Installation

SoftPLC is a 32 bit realtime operating system that uses a file system limited to the DOS compatible 8.3 filename.ext (i.e. short filename) format.

Here is a picture of a runtime directory tree that has the Java support and the core SoftPLC support installed:

\SOFTPLC
    \APP
        * (apps here)
    \FTP
        ALWAYS.LST
        MODULE.LST
        NETWORK.LST
        readme.txt
        STARTUP.LIST
    \RUN
        MODLET.LST
        ALWAYS.LST
        STARTUP.LST
        MODULE.LST
        *.dll
        *.BIN
        *.CFG
        RUNFTP.BAT
        RUNSPLC.BAT
        SOFTPLC.EXE
    \TLM
        *.tlm
\LST
    \SYS
        ALIAS.LST
        RESOURCE.LST
        SERVER.LST
        SERVLET.LST
        USERROOT.LST
    \USR
        ALIAS.LST
        RESOURCE.LST
        SERVER.LST
        SERVLET.LST
        USERROOT.LST
        USERS.LST
\JAR
    RT.JAR
    SPLC.JAR
    \MODLET
        * (modlets here)
    \SERVLET
        * (servlets here)
\HTM
    \USR
        * (website files here)
    \SYS
        * (global webserver files)

All SoftPLC's include the required version of RT.JAR (Sun's Java Runtime Environment). The default installation location for RT.JAR is in the \JAR folder in SoftPLC.

The SoftPLC JVM, called MachJ.TLM, is loaded as a normal TOPDOC Loadable Module (TLM) under SoftPLC. To load the TLM, you use TOPDOC NexGen's PLC Configuration Editor. Select to USE machj.tlm.

Then, you need to set the module options. You simply edit the text string in the Options column with your desired parameter values. The supported options may occur in any sequence. Each option consists of a NAME and VALUE pair that has the general format:

NAME=VALUE

with no spaces between NAME, equal sign, and VALUE.

A full example showing several options (all one line):

DRIVER=MACHJ.TLM JAVATIME=8 HEAP=16000000 
CLASSPATH=c:\jar\splc.jar;c:\jar\rt.jar;c:\jar\modlet\mod.jar; JSTACK=12000

The machj.tlm options are:

CLASSPATH=<list of paths>

<list of paths> is a semicolon separated list of places that the JVM is to look for bytecode for the Java programs you want to run. Each element in the list may be either 1) a JAR file or 2) a subdirectory. Normally your classpath will always have c:\jar\splc.jar;c:\jar\rt.jar as the first two paths.

Note

Bytecode comprising a "Servlet" is an exception. It is loaded by the SoftPLC web server from information that is supplied in its configuration files, so there is never a reason to add a path to the \jar\servlet directory.

The JVM first looks to see if there is an environment variable CLASSPATH= and if so, that is the default classpath. If the CLASSPATH option is supplied in the module editor (and in MODULE.LST), it fully overrides the CLASSPATH environment variable. Most users use the CLASSPATH option and not the environment variable.

HEAP=<maximum Java heap in bytes>

<maximum Java heap in bytes> must be at least 7000000 and can be much larger if you have enough RAM. If this option is not provided, the default value is 7000000. This value leaves about 7 MB remaining on a 16MB system for the core (non-Java) SoftPLC software. You must have at least 16MB of RAM in your CPU to run the JVM under SoftPLC. For the Tealware CPU (Cat No SPLC-2) the recommended HEAP value is 3500000. Commas are not allowed.

Example: "HEAP=56000000"

JAVATIME=<java time>

<java time> is the amount of “pause” time that the Ladder Thread yields to Java Threads at each “check point”. A check point is a point in the Ladder Logic Interpreter’s scan where it checks on the O.N.E. queues (and may call some of the TLM’s giving them periodic control of the CPU). A check point occurs unconditionally at the end of each Ladder Program scan. In addition to that one check point, you may get additional check points every <X> number of rungs of ladder logic scanned. <X> is configured in the STARTUP options tab in TOPDOC. If <X> is greater than or equal to the total number of rungs per scan, then you will only get one check point per Ladder Program scan.

At each check point, you can cause the main Ladder Thread to yield to normal priority Java Threads for <java time> milliseconds. Since the Ladder Thread runs at a higher priority than normal priority Java Threads, without this mechanism, only the main Ladder Thread will actually run Java code. All normal priority Java Threads will be starved for CPU time. By yielding from the Ladder Thread for specific amounts of time to all the normal priority Java Threads, you can specify the (nearly exact) amount of time that is spent running Java code collectively by all the normal priority Java Threads.

When <java time> is actually applied, SoftPLC rounds it up to the nearest clock tick. On SoftPLC this is currently a 4 msec granularity.

Example 1: Say you had a 4000 rung program and you wanted to spend no more than 16 msecs executing Java code (in normal priority Java Threads) per scan of Ladder. You could set the comm check interval to 1000, giving you a total of 4 check points per scan. Then at each check point you would choose to yield 4 msecs to normal priority Java Threads. Do this with the JAVATIME=4 option.

Example 2: Say you had no Ladder Logic and were doing everything in normal priority Java Threads. You still have a Ladder Thread scanning the end of program statement, and it will have a single check point pertaining to the end of program. You could supply JAVATIME=20 which would give you 20 msecs of Java time per ladder scan. Since the ladder scan is so fast in this case, the CPU would almost immediately yield back to Java code for the next 20 msecs. This essentially gives the Java Virtual Machine almost all the CPU time, but every 20 msecs the main Ladder Thread will run and service the O.N.E. queues for TOPDOC and any MMI.

Example 3: This example assumes you are familiar with the Java Toolkit for SoftPLC. Say you had no Ladder Logic and were doing everything in Java language, but doing it from the main Ladder Thread in the Modlet scan() method. In this case, there is no competition for CPU time since there is only one Thread. It will still scan the end of program statement in ladder, but your Java code will get control in that check point via the scan() method. You need supply no comm check interval since there is no CPU time competition. You will however, have to regularly return from the scan() method so the Ladder Thread can do the O.N.E. queue checks.

Warning

Since the JAVATIME=<java time> option is so important to system performance, it is best to get help from an expert. Call SoftPLC for advice or consult your in-house expert.

 

JSTACK=<maximum Java stack size in bytes>

<maximum Java stack size in bytes> must be at least 2000 and defaults to 8000 if this option is not provided. This is the size of each Java thread’s stack. You need only adjust this larger if you see a StackOverflowException while running your application.

Example: "JSTACK=12000"

NSTACK=<maximum Native stack size in bytes>

<maximum Native stack size in bytes> must be at least 150000 and defaults to 150000 if this option is not provided. This is the size of each Native thread’s machine stack. You need only adjust this larger if you see a StackOverflowException while running your application.

Example: "NSTACK=200000"

COMPORTS=<list of ComPorts>

<list of ComPorts> is a comma separated list of serial ports that you wish to make available to Java programs under SoftPLC. If you are not using Java for serial ports, do no use this option.

ComPorts are numbered from 1 to 36. Each ComPort number is implemented by hardware residing at a particular IRQ and IOPORT, as given by COMGENIE.TXT. ComPorts which are not to be used by Java applications should not be given in this option. The <list of ComPorts> will cause an array of Java ComPort instances to be created in SPLC.port[], such that array element SPLC.port[0] will be a ComPort assigned to the first port number in the list, element SPLC.port[1] will be a ComPort assigned to the 2^nd number in the list, etc.

Example 1: "COMPORTS=1" will assign SPLC.port[0] to COM1.

Example 2: "COMPORTS=3,28,1" will assign SPLC.port[0] to COM3, SPLC.port[1] to COM28 and SPLC.port[2] to COM1.

Do not put in a trailing comma. Again, spaces are not allowed. The default is to create SPLC.port[] with length zero, which means you will not be able to use the serial ports with Java applications.