Handling text files

With ADAPL, you can use texts that are read from separate text files. These are typically texts you'd like to present to Collections users in a message box or for printing fixed texts to an output format, both automatically in the current interface language by the way. You can add texts to these files, create new ones or edit existing ones but note that existing texts are probably already in use somewhere so be careful when chaning existing texts. You'll find all text files in the \texts subfolder of your Axiell application. They have names like adlib0.txt, adlib1.txt, admuse4.txt etc. To Collections and ADAPL, the file name must always be used without the number. The number specifies the language of the contained texts, but Collections and ADAPL automatically match a specified text file name like adlib.txt to the file name with the number of the current interface language.

The texts specified in a text file for use in Collections and ADAPL should meet the following conditions:

• The texts must be in UTF-8 BOM format.
• Each line must begin with an ascending line number, starting with 1, without skipping any numbers. If you want to reserve numbers for future use, you should give the line a number, but leave the rest of the line empty.
This construction makes it possible to distinguish between the number and the first character of the text line, which may also be a number. Otherwise it would be impossible to tell what was the number of the text line and what was the text itself.
• Comment lines start with an asterisk (*).
• There are no spaces between line number and text. If there is a blank space, it will be considered as part of the text and will therefore be printed.

Example of a text file with just two lines:

* date.txt
1Error: you can only enter today as the date.
2Error: the week number you entered does not exist.

The following functions are available for use with text files:

Instruction

Brief description

openfile

Opens text file (to read texts from it)

closefile

Closes text file (from which texts are read)

closeallfiles

Closes all files opened with openfile

text$

Fills text variable with text from a certain line number

So you can have text files for different purposes (like different procedures or data sources), which you have to open explicitly if you'd like to use them in an adapl. The reference to the opened file ends up in handle variable that you must declare in the adapl too (see below for an example) and you must reference this handle whenever you want to extract a line of text.
For one text file though, you don't need to specify such a handle if you specify the name of the file name in the (Text files) Adapl option on the Advanced properties tab of the application structure (.pbk) in the Application browser. This setting is usually ../texts/adlib.txt. Every line of text from this file can be read with the text$ instruction, without having to open it or using a handle. So you can place all of your new texts in the adlib.txt file for easier programming.

Using translations of texts

If you want your application to be available in a number of different languages, you will not be able to have fixed texts in the adapls. In other words, you will have to use different text files for the various languages.

In a text file for use in adapls, you usually only store texts in a single language, so only in English or only in Dutch etc. So if you add or edit texts you'll have to do that in the right file. In the file name, the number represents the language in which the file has been written (English = 0, Dutch = 1, French = 2, German = 3, Arabic = 4, Italian = 5, Greek = 6, Portuguese = 7, Russian = 8, Swedish = 9, Hebrew = 10, Danish = 11, Norwegian = 12, Finnish = 13 and Chinese = 14). Text file names without language extension cannot be used: even a text file in the default language (English) should have the "0" language at the end of the name.

An example in ADAPL:

The following piece of code could be part of a before-storage adapl to check whether today’s date has been filled in as date (tag: DA) and whether a valid week number has been filled in (tag: WE). Translations of date.txt are used to obtain message texts in the current interface language.

*Checks date and week field.
integer texthandle
* open textfile:
texthandle = openfile('../texts/date.txt',0)
if (texthandle=-1) { /*error
 /* display "Error opening" text from general adlib.txt
 errorm text$(201) + ' date.txt'        
end
}
 
if (DA <> date$(7)) {
 /* display "invalid date" text from date.txt
 errorm text$(texthandle,1)  
}
if (val(WE)=0 or val(WE)>53)) {
 errorm text$(texthandle,2)
 }
closefile (texthandle) /*close textfile