ADAPL programming: instructions

ADAPL instructions

ADAPL instructions are simple words used as directions to the compiler. They are divided into the following categories:

•	Compiler instructions are direct instructions to the ADAPL compiler.

•	Declarations define variables and their data type.

•	Output instructions take care of output to screen, printer or file.

•	Control instructions take care of the execution sequence within a program.

•	Statements can influence the results of procedures.

•	FACS instructions offer access to Adlib databases.

•	Functions are for manipulating data.

Compiler instructions

These instructions are executed by the compiler during compilation.

Instruction	Short description
include	The contents of the file with the .inc extension specified behind the include instruction will be inserted here in the main adapl code for compilation only and compiled along with the rest of the main code. "Include" files can be used to store general ADAPL code which can be used by multiple more specific adapls.
quit	A rarely used instruction. Makes the compiler stop compiling. If present, errors or warnings will be displayed, but no executable (.bin) file will be generated.

Declarations

With the exception of FACS variables, database variables (field tags from the currently processed record) do not need to be declared. They are implicit and have fixed characteristics.

So-called local variables however, must always be declared with one of the following instructions: INTEGER, NUMERIC, or TEXT. Multiple variables (give them a descriptive name) of the same type can declared at once by separating their names by a comma and a space. All three types support arrays.

INTEGER variable1, variable2[dimensions], ...

NUMERIC variable1, variable2[dimensions], ...

TEXT variable1, variable2[dimensions], ...

The names of the variables must comply with rules described here. A variable is declared as an array (repeated variable) by adding dimensions. These have the format [a], [a, b], [a, b, c] or [a, b, c, d], in which a, b, c, and d define the size of the dimensions.

During the declaration of variables, internal memory is set aside for them. This means that the amount of internal memory in your system can limit the number and length of variables used. It is particularly important to take this into account when declaring very large arrays.

TEXT variables without specific dimensions are always one character large. If a single dimension is given, this will be taken as the maximum allowed length of the text. If several dimensions are given, the last one will be the length of the elements. This system enables you to address each character in the array separately. If the string you will be storing in a text variable may just as well remain small or get very large, you can specify the length dimension as zero. The memory for the text variable will then be assigned dynamically, as required by the data you store in it.

Examples:

text A[20]	Single text variable with maximum length 20
text B[0]	Single text variable with undetermined length
text C[3, 20]	Text array of 3 strings, maximum length of 20 each
text D[3, 0]	Text array of 3 strings, length undetermined
text E[5, 3, 20]	Text array of 5 arrays (15 strings of maximally 20 characters)
integer N	Single integer variable
integer M[5]	Array of 5 integers
numeric O[2, 3, 2, 6]	Numeric array with 4 dimensions (72 elements)

Output instructions

The following instructions take care of adapl printing or error display on screen.

Instruction	Short description
errorm	Displays an information message, a warning message or error message on screen.
onsoj	Subroutine that is carried out when an adapl-only print job is started.
oneoj	Subroutine that is carried out at the end an adapl-only print job.
onsop	Subroutine that is carried out at the beginning of a page during an adapl-only print job.
oneop	Subroutine that is carried out at the end of a page during an adapl-only print job.
output	Sends the line built up by print instructions to the print file.
pdest	Sets the destination of the print jobs.
print	Builds up the print line.
setfont	Sets font type and point size for an adapl-only print job to PDF.
wordcreatedocument	Exports records to a Word template from within an adapl-only print job.

Control instructions

Control instructions control the order of execution of statements in the program. ADAPL instructions are carried out sequentially from top to bottom unless the program changes the order of execution itself. ADAPL has three ways of doing this: jump instructions and subroutines, conditional execution, and loop control.

Jump instructions and subroutines

Instruction	Short description
end	Execution of the adapl is terminated. Return to the calling program.
gosub	Jump to a line with a particular number label in the ADAPL program, but after return jump back to the point from which you jumped.
return	Continue execution at the line following the last encountered gosub.

Conditional execution and loop control

ADAPL incorporates conditional execution using the IF ... THEN ... ELSE, SWITCH ... CASE, DO ... UNTIL, and WHILE constructions. During conditional execution, instruction blocks can be used instead of single instructions. An instruction block starts with a left curly bracket { and ends with a right curly bracket }. The left curly bracket of the instruction block must be on the same line as the keyword THEN, ELSE, SWITCH, CASE, DEFAULT, WHILE or DO. The right curly bracket must be on the same line as the ELSE or UNTIL keyword. If no ELSE keyword is used, the right curly bracket can be placed either following the last instruction in the block, or on a new line. If the instruction block consists of a single instruction, you need not use the brackets. The whole construction will then be on one line. The THEN keyword can be omitted: in that case the left curly bracket must be on the same line as the IF keyword, behind the condition.

Below, you will find a short description of the various control instructions.

Instruction	Short description
if (...) { ... } else { ... }	checks that the if condition is complied with, then carries out the then instructions. If the if condition was not complied with, the else instructions are carried out. One of the two instruction blocks will therefore be carried out. An else block is not mandatory.
switch (...) case {...} case {...} case {...} default {...}	compares each case expression with the switch expression. If a comparison evaluates to true, the code following the concerning case statement is executed. If all comparisons fail, the default code is executed, if present.
while (...){ ... }	As long as the expression behind while is true, the instruction block will be carried out.
do { ... } until (...)	carries out the instruction block, then see if the until condition is complied with, and then carries out the instruction block again as long as the expression remains true. The instruction block is therefore carried out at least once.

Statements

select no

What select no does in an adapl depends on the purpose of the adapl. Generally speaking, select no can be used as a kind of filter, in various situations:

•	Before storage adapl: a select no in a before-storage adapl prevents the current record from being saved and leaves it open in edit mode. You can use this if the user isn't allowed to save a record before it meets certain conditions validated in the adapl.

•

Before edit adapl (Collections only): a select no in a before-edit adapl prevents the record from going into edit mode and leaves no lock. A red warning will appear with the text: Not allowed to edit record <priref>. You could precede the select no with an errorm without severity code or with severity code 1 (both giving an orange message) to explain to the user why the record is not allowed into edit mode. Instead of this construction though, you could also use a single errorm with severity code 2, which prevents edit mode as well and allows you to explain the reason why at the same time.

•	Delete adapl (an adapl used before deletion of a record): if the delete statement contains a condition with which the record complies, so that the program runs through a select no, the record in question will not be deleted.

•

Import adapl: if the record complies with the conditions set in the adapl, so that the program runs through a select no, the record will not be imported. Note that an import adapl does not import records itself: per record which is being imported, it processes data from the exchange file to allow for some data conversion before it is actually written to the target fields.

•

Print adapl: if the adapl runs through a select no, printing will stop after the current record. Print adapls can either be stand-alone adapls or output formats associated with a data source. Output formats are executed for every record marked for printing, while the stand-alone adapls must have built-in routines to search databases for certain records and print them; therefore their construction differs significantly. Select no only makes sense in output formats.

•	Link screen adapl: if the adapl runs through a select no, the currently found record will not be listed in the Find data for the field window.

•

Select (Advanced search) adapl: (not yet supported in Collections) if the adapl runs through a select no, the currently found record will not be included in the search result (and the reserved variable &I will not be incremented). This type of adapl can be called from within the Advanced search, with the syntax: <search statement> adapl <adapl_name>, e.g. all adapl findmultipleoccs.

•

Sort adapl: if the record complies with the conditions set in the adapl, so that the program runs through a select no, the record will not be included in the sort. Note that sort adapls do not actually sort records. You can use them to fill a tag with a compound value for example, and use that tag to actually sort on by entering it in the appropriate sort option in Designer or in Collections' sort functionality.
In the following example, a record will not arrive in the sort output if the value of the ‘OM’ field is equal to 0, i.e. if nothing has been filled in, if the field contains letters, or if a 0 has been entered. In all other cases, the content of the field will be formatted to 2 digits.

* Add leading zeros to OM field for alphabetic sorting of integers
* (2 characters)
if (int(val(OM)) = 0) {
select no
end
} else {
OM = str$(int(val(OM)),'##')
}
end

Note that select no does not end execution of the block or loop it is in: after select no the next line of code is executed normally. If you do not want the rest of the adapl to be carried out, include an end call after the select no in the if-statement.

FACS instructions

FACS instructions provide ADAPL access to different database tables for searching and editing purposes. FACS (File Access Control System) uses aliases to refer to a database table or (dataset) subset therein. These aliases are typically defined in the ADAPL program itself. This method can be used both for adapls that are started from within Collections and for stand-alone adapls.

The FACS system consists of the following instructions:

•	Alias declaration: FDSTART, field declarations, FDEND

•	Accessing: OPEN, CLOSE, CLOSEALL

•	Searching: READ

•	Writing, updating or deleting records:WRITE, DELETE

•	Other: CLEAR, LOCK, UNLOCK, ISIN, RECCOPY

ADAPL functions

ADAPL functions are built-in routines which compute a value from one or more arguments, and then return the result to the calling program.