The customer app from the series Building a customer app in Uniface 10 got seventeen new forms and menus in its last two stages. Eleven of the forms ended with the same block of five small helper entries: formatting a number, appending a line to a list field, opening a file, reading the export folder, closing the form. Three more carried parts of it. The block was appended to the form sources when the forms were generated.
That works until one helper needs a fix. Then every one of those forms has to be regenerated, imported and compiled. This article is about moving the helpers into one place: an IncludeScript library in the repository, created by XML import, and pulled into a form with #include.
Tested with Rocket Uniface 10.4.03 Community Edition (10.4.03.021) on Windows, October 2026. The app uses SQLite through the SLE driver (SQLite 3.50.2).
IncludeScripts in two sentences
An IncludeScript is a named piece of ProcScript stored in a library in the repository. The compiler replaces a line #include LIBRARY:NAME with that text before it compiles the component, so the helpers end up in each form exactly as if they had been pasted in.
Where the definition comes from
New forms in this project are created by XML import, not painted by hand (see the earlier article on generating forms from XML). For a library there was no exported example in the project. The installation has one, though: uniface\misc\utemplates.xml contains the table descriptions for every repository object type, including the two needed here:
-
ULIBINC - the IncludeScript library itself (key
UNAME). -
UINC - one IncludeScript (key
UVAR= library name,ULABEL= include name), with the source in the fieldUTEXT.
The import file reuses the <DSC> blocks for these two tables unchanged from the template and adds one occurrence each. These are the data parts of the file that was imported (field descriptions left out):
<OCC>
<DAT name="UNAME">CUSTLIB</DAT>
<DAT name="UKVERSION">7</DAT>
<DAT name="UMVERSION">2</DAT>
<DAT name="UDESCR" xml:space='preserve'>Customer app include scripts</DAT>
<DAT name="UTIMESTAMP">2026-10-17T10:00:00.00</DAT>
<DAT name="UPURPOSE">N</DAT>
</OCC>
<OCC>
<DAT name="UTIMESTAMP">2026-10-17T10:00:00.00</DAT>
<DAT name="UVAR">CUSTLIB</DAT>
<DAT name="ULABEL">UI_LIB</DAT>
<DAT name="UKVERSION">7</DAT>
<DAT name="UMVERSION">2</DAT>
<DAT name="UDESCR" xml:space='preserve'>Shared form helpers</DAT>
<DAT name="UPURPOSE">N</DAT>
<DAT name="UTEXT" xml:space='preserve'>entry FMT
params
numeric pValue : IN
...
The source in UTEXT is XML-escaped (>= becomes >=). UPURPOSE is N (normal) here; in the template the system rows use T for templates and P for palettes.
The import via the IDE menu Import XML... reported "Successfully imported 2 records." Afterwards the repository database showed the library row and the include row. The source is not stored in a column of its own: it sits in the UCOMMENT field inside <unimeta><UTEXT>...</UTEXT></unimeta>. A comparison of that text with the source file showed both identical.
A helper that belongs in the library
Besides the existing helpers, the library got one new entry. Every form dims its editing buttons for users with read-only rights, and each form wrote that comparison itself. Now the rule lives in one place:
entry ROLE_AT_LEAST
params
string pNeeded : IN
boolean pOk : OUT
endparams
variables
string vUser, vRole
numeric vHave, vWant
endvariables
activate "USER_SVC".CURRENT_USER(vUser, vRole)
vHave = 0
if (vRole = "READ")
vHave = 1
elseif (vRole = "EDIT")
vHave = 2
elseif (vRole = "ADMIN")
vHave = 3
endif
vWant = 3
if (pNeeded = "READ")
vWant = 1
elseif (pNeeded = "EDIT")
vWant = 2
endif
pOk = 0
if (vHave >= vWant)
pOk = 1
endif
return 0
end
An unknown role ends up with level 0 and gets nothing; an unknown requirement is treated as the highest level. Both defaults fail closed.
Using it in a form
The ticket form was the first form without the pasted copy. Its source ends with one line:
#include CUSTLIB:UI_LIB
and its rights check calls the shared entry:
entry SET_RIGHTS
variables
string vUser, vRole
boolean vOk
endvariables
activate "USER_SVC".CURRENT_USER(vUser, vRole)
INFO.TKT_DMY = "Logged in as %%(vUser) (%%(vRole))"
call ROLE_AT_LEAST("EDIT", vOk)
if (vOk = 0)
$fieldsyntax(BTN_CREATE.TKT_DMY) = "DIM"
$fieldsyntax(BTN_ASSIGN.TKT_DMY) = "DIM"
$fieldsyntax(BTN_SET_STATUS.TKT_DMY) = "DIM"
$fieldsyntax(BTN_COMMENT.TKT_DMY) = "DIM"
$fieldsyntax(BTN_INTERNAL.TKT_DMY) = "DIM"
(The list of dimmed buttons goes on in the same way.)
Read the compiler output, not just the error count
In the IDE's assignment file, $INCLUDE_NOT_FOUND_LEVEL sets the severity of the message for a missing include. Its comment lists 0 = info, 1 = warning (default), 2 = error, and the installation uses 1. With the default, a wrong library name is reported as a warning, not as an error, so a form can compile with errors 0 while its helpers are missing.
For the ticket form, the compiler output showed "errors 0" and exactly one warning: 1016, the usual note that the form's dummy entity is not in the application model. No include message. In the click test, the helpers worked: lists were formatted, the report opened in the browser, and with a read-only user every editing button was dimmed while the read functions stayed available.
The form generator of the project also checks that every button has a matching entry. Before the change it only searched the form source, so it would have reported DO_CLOSE as missing. It now replaces the #include line with the library source before it checks.
What is left
The older forms still carry their copies. Each one switches to the include the next time it is changed anyway, so no form is touched only for this.
Takeaways
-
uniface\misc\utemplates.xmlis a good source for the XML structure of repository object types that you have no export of. - An IncludeScript library can be created by XML import, with the library in ULIBINC and the include text in UINC.
UTEXT. - With the default
$INCLUDE_NOT_FOUND_LEVEL, a missing include is only a warning. Check the warnings, or raise the level in your own assignment file. - Shared rules such as "who may edit" belong in the include, not in each form.
Top comments (0)