|
|
PicsRPG supports the concept of template files. These are regular HTML pages that contain special tags that are interpreted by PicsRPG immediately before transmitting the page to the browser. PicsRPG tags are encapsulated in square brackets and may include a override format (e.g. [A200:Value%5.3f]).
Starting with PicsRPG v2.2, build 54 templates will recognize parameters included with the URL. HTTP syntax rules allow parameters to be appended to a URL following a question mark (?). Each parameter consists of a name and a value, separated by an equal sign (=). Parameters are separated from each other using the ampersand sign (&). So, a simple example would be:
http://picsrpg/mytemplate.thtml?parm1=27&parm2=c33.u2.v00
In the example, 'picsrpg' is the name/address of your web server; 'mytemplate.thtml' is the name of your template; 'parm1' is the first parameter, with a value of '27'; and 'parm2' is the second parameter, with a value of 'c33.u2.v00'. Theoretically, the number of parameters is unlimited, but in practice, PicsRPG limits URLs to a maximum length of 4096 characters -- both before and after expansion.
Parameters are used like any other tags and therefore, you must be careful not to duplicate an existing tag name with a parameter, because doing so would effectively replace the parameter with the built-in tag. Parameters may be used as part of an internal tag, allowing you to create parameterized templates that report a different set of points based on the URL parameters. For example, using a tags like
[C3[bldg].U[unit].T[cell]1A:Value]
[C3[bldg].U[unit].T[cell]2A:Value]
[C3[bldg].U[unit].T[cell]3A:Value]
[C3[bldg].U[unit].T[cell]4A:Value]
[C3[bldg].U[unit].T[cell]5A:Value]
[C3[bldg].U[unit].T[cell]6A:Value]
[C3[bldg].U[unit].T[cell]7A:Value]
[C3[bldg].U[unit].T[cell]8A:Value]
[C3[bldg].U[unit].T[cell]9A:Value]
[C3[bldg].U[unit].T[cell]0A:Value]
with a URL such as
http://picsrpg/demo.thtml?bldg=3&unit=4&cell=1
would result in the values of C33.U4.T11A through C33.U4.T10A being reported. Parameters may also be used alone, just like other tags, as labels, special values or whatever is needed.
| Tag Name | Description |
| System:Name | Name of the PICS System (not the subsystem, node, or NT system name) |
| System:PicsTime | Current PICS time (GMT), formatted using the defined Plant time format string. |
| System:PlantTime | Current Plant local time, formatted using the defined Plant time format string. |
| Stat:[tbd] | Eventually, some of the server (and possibly other PICS) statistics will be available here. |
| PointName:Name | Name of the named point. (This was added to make repeat block processing easier.) |
| PointName:Value | Current value of the named PICS data point. Analog points will be formatted using the format from the static database, unless an override format is given. Digital points will be the on or off state (as appropriate), also using the same formatting rules. |
| PointName:nValue | Current numeric value of the named PICS data point. (NOTE: Time and Subsystem Status points do not have an nValue) |
| PointName:Desc | Description of the named point, from the static database. |
| PointName:Units | Units from the static database. This field is typically empty for digital, subsystem status, time, and mode points |
| PointName:Color | The point's color from the static database as an HTML color string (e.g. 14 in the database is #FFFF00 for HTML). These colors may be used in HTML color commands to render points as directed in the database. |
| PointName:AlarmColor | The color associated with the point's current alarm level as an HTML color string. |
| PointName:AlarmLevel | Text translation of the point's current alarm level. |
| PointName:Quality | Standard one character quality code, unless a quality format is provided (as defined for Recall Display). |
| PointName:Status | Complete point status field, same us used in tabular reports. |
| PointName:PS | Point Status value in hex (0x00000000) format unless otherwise specified. |
| PointName:PSX | Point Extended Status value in hex (0x0000) format unless otherwise specified. |
Effective with PicsRPG version x.y build a.b (051216), some additional tags were added.
| Control Tag Name | Description |
| group:groupfile:title | Extracts the title (if any) from the specified group file. This is useful when using PicsRPG's group repeat block feature (see below). |
| group:groupfile:pointN | Extracts the name of the Nth point entry in the group (if that entry exists). If the number is missing, the first point will be returned (same as if 'point1' had been specified). |
Effective with PicsRPG version x.y build a.b (051123), the concept of a control tag was added.
| Control Tag Name | Description |
| set:magic | Reports the 'magic' value formatting option. "Magic" value formatting will cause points with conditions such as hardware errors to show a value such as '(no idvm)' instead of the last known numeric value, and when a numeric value is required, the system-wide magic value (-100 by default) will be provided. The current magic setting will be reported as either 0 or 1 if the setting is disabled or enabled, respectively. |
| set:magic=state | Sets the 'magic' value formatting option. The state must be one of ("yes","on","true","enable" or a non-zero numeric value) to allow magic value formatting. To disallow magic value formatting the state must be one of ("no","off","false","disable" or a zero numeric value). |
Recently, a new set of tags were added to PicsRPG, at the request of USEC/PGDP. PicsRPG now understands all of the tags that the PICS Real Time Data DDE Interface understands. The format used for these new tags is similar to the format required by Microsoft Excel, with the point name coming last rather than first as in the original PicsRPG tag set. These are not accessible via DDE, they only share names and result formats with the PICS DDE server.
| DDE Tag Name | Description |
| dde:xldatetime:pointname | Excel Date/Time (double precision fractional number of days since 12/31/1899) |
| dde:date:pointname | PICS Date (unsigned int number of days since 1/1/1980) |
| dde:time:pointname | PICS Time (unsigned int number of milliseconds elapsed today) |
| dde:onstate:pointname | Digital ON state name (used for a value of 1) |
| dde:offstate:pointname | Digital OFF state name (used for a value of 0) |
| dde:units:pointname | Analog engineering units label |
| dde:type:pointname | PICS Point Type (unsigned integer 1=AI,2=AC,3=AO,4=DI,5=DC,6=DO,7=PI,8=PT,9=PM,10=SS,11=AW,12=BI,13=BO) |
| dde:typename:pointname | PICS Point Type Name (AI,AC,AO,DI,DC,DO,PI,PT,PM,SS,AW,BI,BO) |
| dde:desc:pointname | Point Description |
| dde:stat10:pointname | Point Status, base 10 unsigned integer (decimal) |
| dde:stat16:pointname | Point Status, base 16 (hexadecimal) |
| dde:value:pointname | Point Value |
| dde:xvalue:pointname | Point Value as base 16 (hexadecimal) |
| dde:alarmlevel:pointname | Current Alarm Level Analog:0=Norm,1=Inhibit,2=LW,3=HW,4=LA,5=HA,6=LC,7=HC,8=SX,9=MX,10=OT Digital:0=Norm,1=Alarm |
| dde:alarmname:pointname | Current Alarm Level Name Analog:Norm,Inhibit,LW,HW,LA,HA,LC,HC,SX,MX,OT Digital:Norm,Alarm |
As of the Dec 9, 2002 software release, the template feature has once again been enhanced. PicsRPG's templates may now include repeat blocks. A repeat block is enclosed between a pair of new tags (one to begin the block, and one to end it) and uses a new form of the original point name-based tags to extract data. Within the block, the special symbol '{}' (open/close curly brace (without the quote marks)) is used in place of a point name. The {} symbol will be replaced with each matching point name encountered at the block is repeated.
| Repeat Tag Name | Description |
| rpt:type:control | Repeat block begin tag. The type component may be pmask, rmask, or group. pmask indicates that the control component is an old-style PGDP point name mask (e.g. C31.U*.G******). rmask indicates that the control component is a regular expression point name mask (e.g. C31.U[1-4].G). group indicates that the control component is the name of a group file (e.g. Log-261.pgf). Group file names must be specified fully, but without any drive/path information, as PicsRPG will only look for them in the PICS Groups folder. |
| end: | Repeat block end tag. The trailing colon is required! Anything between the colon and the closing bracket is ignored by PicsRPG. For example, one may store a comment or a copy of the repeat mask to help document the web page source code. |
In theory, repeat blocks may be nested, and you may have more than one block per source file. Neither of these features have been tested in practice, however, so for the time being, you are on your own.
<html>
<head>
<title>PICS Report Generator - Repeat Block Test</title>
</head>
<body text="khaki">
<table border="1" cellspacing="1" cellpadding="3" bgcolor="black">
<tr>
<th>Name
<th>Description
<th>Value
<th>Unit
<th>Alarm
</tr>
[rpt:rmask:C3..U..G]
<tr>
<td>[{}.name]
<td>[{}.desc]
<td align="right"><div style="color:[{}.alarmcolor]">[{}.value]</div>
<td>[{}.units]
<td><div style="color:[{}.alarmcolor]">[{}.alarmlevel]</div>
</tr>
[end:rmask]
</table>
</body>
</html>
As of Dec 13, 2002 (build 36), the template feature has once again been enhanced. to include eval statements. An eval statement is enclosed within square brackets, as are all other tags. However, following the first component is an expression instead of one of the original substitution strings. Point names and some attributes may be used within an expression by enclosing the point name and attribute in curly braces, using the form "{pointname@attribute}" and the point name itself may be the replacement symbol {} to use the current match within a repeat block (see above).
Because the expression evaluator allows complex expressions, there is a possibility that an expression may be incorrectly constructed or otherwise incomprehensible to the eval function. When this occurs, some attempt is made to determine the type of error that occurred, and a message describing the error is emitted in place of the original tag, even by the silent evaluator. This was done to help determine / dignose problems.
Because the expression evaluator may retain variable information internally, we have provided a capability to restore the evaluator to initial conditions in the form of a reset function. The tag [eval/s:reset()] or [eval:reset()] will restore the evaluator's initial conditions -- both forms are exactly equivalent in that neither emits anything to the resulting web page.
Currently, the expression evaluator knows the following attributes for points:
| Attribute Name | Content / Usage |
| value | Current value of the point. If no attribute is named, then value will be returned. |
| const-xx | Conversion constant number xx. At PGDP, const-00 will generally be the slope, and const-01 will be the intercept. |
| minval | Minimum EU Display value |
| maxval | Maximum EU Display value |
Const-xx, minval and maxval all come from the point's static database entry. If other fields are needed, submit a request to EVI to have them added and we'll make them available ASAP.
The tag formats for the expression evaluator are:
| Eval Tag Name | Description |
| eval:expression | evaluate the expression given and emit the result into the web page |
| eval/s:expression | evaluate the expression given silently -- emit nothing (except error messages) |
<html>
<head>
<title>PICS Report Generator - Repeat Block Test</title>
</head>
<body text="khaki">
<table border="1" cellspacing="1" cellpadding="3" bgcolor="black">
<tr>
<th>Name
<th>Description
<th>Value
<th>Unit
<th>Alarm
<th>Min EUV
<th>Max EUV
</tr>[eval/s:reset()][eval/s:row=1]
[rpt:rmask:C3..U..G]
<tr id="TR_[eval:row]">
<td id="TD_R[eval:row]C[eval:col=1]">[{}:name]
<td id="TD_R[eval:row]C[eval:col=col+1]">[{}:desc]
<td id="TD_R[eval:row]C[eval:col=col+1]" align="right"><div
style="color:[{}:alarmcolor]">[{}:value]</div>
<td id="TD_R[eval:row]C[eval:col=col+1]">[{}:units]
<td id="TD_R[eval:row]C[eval:col=col+1]"><div
style="color:[{}:alarmcolor]">[{}:alarmlevel]</div>
<td id="TD_R[eval:row]C[eval:col=col+1]" align="right">[eval:{{}@minval}]
<td id="TD_R[eval:row]C[eval:col=col+1]" align="right">[eval:{{}@maxval}]
</tr>[eval/s:row=row+1]
[end:rmask][eval/s:reset()]
</table>
</body>
</html>
PicsRPG only applies the template filling engine to files with a "thtml" extension. Unknown tokens will remain untouched in the result file. For example, if the string "[sample]" were encountered in a template file, then the same string ("[sample]") would appear in the result page.
|
|