Assignment Files

A Uniface assignment file contains one or more assignment settings, which determine the environment of a Uniface application and control aspects of its behavior. Assignment settings can determine the location of application resources and servers, set environment variables, define application logicals, and set Uniface system settings to influence runtime behavior.

Each application and Uniface product has its own assignment file, usually with the same name as its application shell or executable. When you start an application, Uniface builds an internal assignment file from a global assignment file (usys.asn) followed by a local assignment file (for example, myapp.asn). Settings in the local assignment file take precedence over those in the global assignment file.

In fact, it is possible to have multiple global and local assignment files, because one assignment file can reference another assignment file using the #FILE directive. This makes it possible name and organize assignment files to suit your requirements.

An assignment file is an ASCII or EBCDIC text file (depending on the platform) with the extension .asn, so you can use any ASCII file editor to create or edit assignment files.

Note: If you use non-ASCII characters in an assignment file, the file needs to be Unicode-encoded as UTF-8 or UTF-16, with a Byte Order Mark (BOM) appropriate to the encoding.

Note: On iSeries, if you need to use characters from more than one EBCDIC code page, then you need to save it in Unicode (UTF-16 or UTF-8) encoding. UTF-16 files can only reside in the IFS. A UTF-8 file has CCSID 1208, and a UTF-16 file has CCSID 1200.

Assignment File Syntax

An assignment file is divided into sections, which organize assignment settings and allow Uniface to check the syntax of your assignments. See Assignment File Sections.

The assignment settings themselves typically have the format :

Setting {=} Value

For more information, see Assignment Settings.

In addition to section headers and settings, an assignment file can include:

  • #FILE directives—used to include the contents of another assignment file. For more information, see Including Assignment Files.
  • Comment lines—denoted by a semicolon (;). The semicolon can be preceded by spaces and tab characters, but not by other characters.

    Note:  Comments must be defined on separate lines. They cannot be defined on the same line as an assignment setting.

  • Line continuation markers—the characters %\ can be used to indicate that a path or setting continues on the following line. This can be especially useful in long path specifications, connector parameter lists, or when a line contains strings encrypted by the Pathscrambler utility.
  • Blank lines—to enhance readability by separating groups of related assignments.
  • Caret symbol (^) to escape characters that must be treated as part of the data rather than interpreted by Uniface.

Line Continuation in Assignment Files

Uniface has a limit of 1023 characters per line but not all operating systems support this limit. Long lines are difficult for human users to read and may become even longer when they contain encrypted strings. In such cases, the line continuation marker (%\) can be useful.

When Uniface reads an assignment file containing lines with line continuation markers, the line following the marker is appended to the line having the marker. The marker itself and possible trailing spaces are removed from the line, leading spaces and tabs of the following line are also removed. Spaces or tabs before the %\ marker are not removed. This allows formatting such as the following:

$DB       ORA:database|((username))|%\
$REM_DB   TCP:((machine1+port|user|passwd)) + %\

If you have a very long encrypted line, you can break it up in multiple lines using the %\ continuation marker, as long as you don’t change, add, or remove any of the characters and do not insert whitespace before the %\. For example:

myloggical = (!ASl4K8FAaXujDGZEnAf7%\

When an assignment file containing continuation markers is copied of FTP'd into a physical file on the iSeries, the lines are padded with blanks to fill the fixed record length. Therefore, spaces after %\ are allowed, but no other characters. If some other character follows the marker, the %\ is treated as a literal and not a line continuation marker.

Protecting Sensitive Information

Assignment files can contain sensitive information in path definitions, such as user names, passwords, server and database names. To protect this information, you can use the Pathscrambler utility to encrypt path definitions and other information that has been delimited in the assignment file. For more information, see pathscrambler.exe .

Escaping Literal Characters

Use the caret (^) to escape characters that must be treated as part of the data rather than interpreted by Uniface. This applies to:

  • Encryption or decryption delimiters interpreted by Pathscrambler: (()), (! or !).

    For example, ^!) will be treated as literal !) and not a decryption end marker.

  • Line continuation characters: %\

    For example, %^\ will be a literal %\ and not a line continuation marker.

  • The caret symbol itself, when it is not followed by an alphanumeric character or whitespace.

    For example, ^^\ will be literal ^\

  • Other non-alphanumeric and non-whitespace characters that must be treated as a literals.

Sample Assignment File

;sample assignment file
#file D:\Uniface 10.2.01\common\adm\dbms.asn

$putmess_logfile   =     D:\Uniface 102 Data\log\mylog.log

Assignment File Sections

All assignments that follow a section header belong to that section, until another section header is found, or until the end of the file.

Assignment File Sections
Section Description
[DRIVER_SETTINGS] Connector-specific settings, such as the connector version and connector-specific parameters. The parameters available depend on which connector is in use.
[ENTITIES] Paths to individual entities, giving the target database table a different name than the name of the entity, or specifying the physical file name for database tables for record-level databases.
[FILES] Paths to non-DBMS files.
[LOGICALS] Logical value definitions that you can access in your application using the $logical ProcScript function.
[META_CharSet] Your own mappings between Unicode and the character set specified in LANGUAGE.
[NET_SETTINGS] TLS connection profiles, and their required keys or certificates. These can be used to configure different TLS connector paths.
[RESOURCES] Paths to the locations where Uniface must look for Uniface objects. These are usually .uar files but can also be directory paths. Uniface applications use this section to locate all the objects they need.
[PATHS] Paths to DBMS, network, or GUI drivers. Path assignments can include path-to-connector assignments and path-to-path assignments.
[PRE_START] USTs of Uniface servers that the Uniface Router should automatically start when the Router starts; used only in the Uniface Router assignment file (urouter.asn).
[PROXY_SETTINGS] Proxy settings used by the UHTTP component
[REPORTS_EXEC] Direct the execution of report components to a network path specified in the [PATHS] section. The report component is then executed by the Uniface server identified by the UST in the path definition.
[SERVERS] Server names (USTs) of Uniface servers; used only in the Uniface Router assignment file (urouter.asn).
[SERVICES_EXEC] Direct the execution of service components to a network path, COM connector, or SOAP connector.
[SETTINGS] Settings that control your Uniface application, such as application appearance, I/O behavior, application environment settings, testing, compatibility settings, and so forth.
[WEB] Configure the behavior of the Uniface Web Application Server (WASV).
[WIDGETS] Logical to physical widget mappings in character mode
[USER_3GL] Uniface 3GL extensions to be made available to the application
[XLOGIN] Network paths requiring extended logon

Related Topics