FLEX Commands
Strg+f = Find, Strg+g = Find more
FLEX is the scripting language for the allegro system's main Windows program a99 and its command line program acon.
Almost everything one can do manually can also be done by a FLEX command, and quite a few other things as well. 
For the command line program acon, there are some differences, as indicated in the documentation. 

`Functions Overview`   `Alphabetic Index`

Important: There is an internal Variable (iV for short), not referred to by a name but indirectly. It is a temporary string, living only as long as it is not overwritten by another command. The most relevant commands are   `ask` ,  `yesno`   `message`  and above all  `variable` . Learn these four ¾, and with them the method of using the internal Variable. There are more commands that either write their output into the iV or take their input from there. 
Most commands, when given without an argument, will take the contents of the iV instead. And in most of these cases, the iV is first prepared by a var command, using the contents of fields or variables. 
The iV has no name and doesn't need one, which makes a few things easier. Normally, the iV is used right after having been created; For example, in a command like  insert`#u98 ,  iV is copied into the field #98 of the current record. If the intention is to preserve iV for later use: write  insert`#uxy  to copy it to a user variable #uxy. (Reverse:  variable #uxy  copies the string back into the iV.) 
Apart from this, there is an internal number variable (iN for short), to be used in calculations. See the  evaluate  command. 

How to construct FLEXes
Tip: Always open the Demo database in a separate window. There, you can keep this FLEX documentation open at all times. Enter  h xa  to bring up the overview.
Important examples:  The script  al.job provides many examples for important FLEX procedures.
			Another example is  update.job  which can merge data into a database.

For a99
The simplest way to enter and execute a FLEX in the a99 program is this: 
1. Enter a sequence of commands, separated by \, in the write field (underneath the display area in a99) preceding it with a digit 0, 1, ... 9 
	example:   1 message Index 1 will be shown\index |1 shakesp
    (If a real \ is needed, like in path names, enter \\ ) 
    Press Enter. The sequence will be saved in the user variable #uX1 
2. Execute it: press Alt+digit  (Alt+1 for the example, to activate #uX1) 
3. Change it: Press Alt+r to see the reserve store (background store), select the line beginning #uX1 and press Enter; then change the command text in the write field, save back pressing Enter. 
Direct execution: If you are fluent in FLEX and want a command (chain) executed right away, enter it directly into the write field, preceded with "x`". 
To execute a FLEX file  abc.flx  (consisting of any number of commands), enter  X abc  in the write field. 

acon
For the command line program acon, you need to provide jobfiles containing the command sequence to be executed. 
If  xyz.job  is a jobfile and you want it to work with your database  cat  in  /usr/data/catalog , the configuration being a.cfg), then you start the job in this way: 
   acon -jxyz -d/usr/data/catalog -bcat -ka
Every command takes one line in the jobfile, but you may chain several commands on one line, separated by \ .
The usual "Hello world!" job would require just one line of FLEX code: 
write "Hello world!" 
Just call the jobfile  hello.job  and then enter  acon -jhello

First, some special commands: 

#xyz Text
Text is inserted into the field  #xyz  of the current record. If  Text  is empty,  #xyz will be deleted. 
#xyz can also be a user variable  #uxy  instead of a field in the current record. 
If the iV string is to be composed in a complicated way, one has to use the  variable ... command to compose it, then  insert #xyz  to save it into a field or user variable. 

$xyz Text
Text is inserted into the $-variable  $xyz  (xyz being a name of arbitrary length). To delete  $xyz, use the sequence  var ""\ins $xyz. 
If the first letter x of a variable $xyz name is a capital letter, the variable will be available throughout the session, otherwise only until the end of the FLEX.

The following two, however, have nothing to do with $-variables but only with subfields of data fields:
$a+#xyz Text
The subfield ²a with  Text  as its content is appended to the field #xyz . If  #xyz  does not exist, it will be created. Instead of  '$' the subfield triangle symbol can be used as well, like in 
²u+#90 Meyer      ²u+#90 Meyer²uMeyer is appended to #90 in the current record. 

$a-#xyz Text
If subfield ²a exists, it gets replaced, otherwise ²aText will be appended to #xyz . 
If  Text  is empty, subfield ²a is deleted from  #xyz . 

*#nnn_ABC_XYZ_     	In field  #nnn , replace the string "ABC" by "XYZ" 

_ABC_XYZ_      		Throughout the current record, replace "ABC" by "XYZ" 

The regular commands.  (Presently, only the `German list` is complete)

:label
Jump target. a command jump  label   goes to this position and continues processing with the line that follows 

All command words described from here on may be truncated to 3 or more letters, for example "exp" or "expo" instead of "export", "var" for "variable", "ins" for "insert". In other words: Only the first three letters of every command word are significant. (Exception:  erase). 

ask |iprompt=default    acon
ask +|iprompt=default
Prompts for an input. The input is copied to the internal variable . 
With the  +  set, the input will be appended to the end of the iV content. 
A small input window appears with a slot for the input. 
i   		= Number of  Index to be shown when  [Index] button pressed in the input window 
prompt 	= Prompt string 
(If |i is omitted, a random section of the index will appear) 
An empty input aborts the FLEX command chain. 
The "=default" can be absent; otherwise, default  initially appears in the input area. 
default may also be a field or a #u variable: 
ask |1Author?=#100    initialises the input field with the content of  #100. 
The input, however, is not copied back into the field but to the iV;   insert #100  has to be used to copy this to the field, if wanted. 
The whole of |iprompt=default can be a field tag, the field text then has to consist of  the prompt plus default string. This way, prompt and default can be constructed individually and based on the record content. 
 
call program command   acon
Call program command
cAll program command
CAll program command
The program command can be anything one might enter as a DOS command. 
The C makes the called program an independent process in its own window, whereas the c means that a99 will be halted until the called program terminates. The A means that the called program's window will be minimized. This is useful to run external DOS programs when it is not necessary to have a display of the DOS window. 
For example     call x d-wrtf.apr   
or     call del e.adt
a99/alcarta (and the FLEX) halts for as long as the external program is executing. If the external program produces a file E.ADT, this can subsequently be loaded using "read" (q.v.) : it will then be merged into the current record. This way, external data can be "smuggled" in. 

choose find command
Builds a result set  and  displays it. (find does not display it) 
The short title entry of the chosen record is copied to the internal Variable. A subsequent load command loads this record. 

close    acon
If earlier in the same FLEX (!)  a file was opened for reading by an  open  command, this will close it. This is done automatically at the end of the FLEX. 

close res    acon
	The currently open result list is closed AND deleted from the search history list. With  if no ...  it can be checked whether it had been closed already. 

close view    (see also view)
	The currently open ViewList is closed. With  if no ...  it can be checked whether it had been closed already. 

close xport    (see also xport)
	Closes the currently open output file. Use  if no ...  to check if it had been closed already. 

copy    acon
The current record in its current state is copied and thus becomes a new record. After this, use commands of the  #xyz  type, replacements, or insert ..., to modify the new copy, then  put  for saving - or end the FLEX to resume manual editing. 

date b   acon
	(b=width of the date string, 8-17 bytes; date 8 means just the date (YYYYMMDD), 
	date 17  means date plus full time  (YYYYMMDD/HH:MM:SS) 
Date (and time) will be copied to the iV. 
As usual, the iV can be copied to any field or subfield by  insert ...  

delete  ABC
Delete file  ABC . Use  if no command  to check if it didn't work. 

display xABC
deposit xABC
Execute section #-x in the display parameters. The string ABC will then be in the variable #u1 which can be used for whatever purposes.  This way, the power of the export language can be put to use within a FLEX. 
deposit  means the display will not change bacause the processing is only done internally. This makes sense for complex manipulations that go beyond  the capabilities of the FLEX language. #u1 can serve for decisions in the parameter section. Any output that results from the section will be deposited in the iV - hence the name "deposit". 
The most frequent use of this feature will be to produce some #u variables or some particular string in the iV. 

display p name
Load other display parameters and re-display current record 
e.g., display p d-alfa   Load D-ALFA.APR 

download   see   export

end     acon
Ends the FLEX. Useful after yesno und noyes , for example: 
if no end   if the answer was no, then end the FLEX 

erase    acon
Deletes the current record. (a99: This does not require  access=3  in the .INI file.) Therefore, deletions can be done in a controlled way. Even in alcarta! There's no danger there because the user has no data input field to enter their own FLEXes - even if they knew how to do it. 

evaluate Expression   acon
The Expression will be interpreted arithmetically. It can contain the usual operators +, -, *, / and ^, and the operands can be literal numbers, datafields, #u-Variables, and $-variables. Execution is strictly from left to right with no parentheses allowed. 
Lack of an  Expression  means the iV content will be used instead.

export    acon
Exports the current record (as via the Export menu). 
If you want to have one specific section  #-X  executed only, you can set a variable first, using  var xxx\ins #uFL, and include something like this at the beginning of the parameters:  #uFL +X e0  

export p name    acon
Load parameter file  name.cPR for exporting 

export f filename   acon
export f +filename   acon
Subsequent exports go into the file  filename  . 
The '+' means "append to" (rather than "overwrite" which is the default) 

export set   acon
Exports the entire result set, record by record, in the same way.  The order of  the records can be set beforehand using the order command.

extern   (Same as Alt+t) 
Writes the current record to E.ADT and brings up the external editor. 
Upon return, the externally edited record can be re-read to replace the one in memory. 

fcopy name1 name2
File name1 is copied to name2. If name1 name2  are missing, the iV content is used, which means there have to be two names there, prepared by a var command. Both names may be full path names. Be sure to use \\ instead of a \ within a FLEX, but not in the iV text. 

fetch number   acon
fetch ^code
From the file previously opened by open ,  number  bytes are read into the internal variable. 
ASCII codes 0,1 ... 32  are replaced by ^@, ^A ... ^  , the code  ^ itself is replaced by  ^~. 
The second command will read everything up to and including the next occurrence of the code  code (decimal, 0...255). 
Use if no ... to check if anything could be read at all, and  if cancel ...  to check if the end of file had been reached. 
The max number of bytes to be read in one fetch is 8000.. 
Use  write ^ to write the iV text in the same way, exactly as read. 
If one line is to be read (terminated by codes 13 10 or 10 alone): use --> get (this does not convert the codes 0,..,32!), write one line using  write . 

file filename / file +filename
The display content is copied to the file filename. If the file type is .rtf, then RTF formatting will be used, in other cases plain ASCII formatting; if set c1 had been stated, ANSI (Windows) codes instead of ASCII will be written. 
The  '+'  means to append data to the end of filename instead of overwriting it. 

find    acon
find find command 
Find 
Find find command
to build a result set. Using the small  'f' it will not be displayed but become the current result set upon which to operate with commands  next, prev, or download set  . If  find command is absent, the content of the iV will be used. Preceding action can thus construct a find command based on the current record The first record of the result set will be loaded before the FLEX continues, i.e. it becomes the current record. 
F instead of  f means the set will be displayed and the FLEX ends. 
If the find command has no result, the FLEX is aborted. 
Find offline
Special case! The offline file will be displayed. 

first   [opposite: last ]   acon
The first record of the current result set, as arranged in the brief display window, will be loaded. 
Use if no ... to check for failure (because of the result set being empty).  
Say  first r  to load the brief line into the iV in addition.  
next then loads the next record. 

first #   [opposite:  last # ]   acon
Read the first record  (internal rec number 1)  of the database display it. Use  find #1 to load it with no display. 
next #  then loads the next. 

first off   [opposite:  last off ]
Load the first Offline file record and it. Use  if no ... to check for failure (i.e., empty offline file). 
next off  then loads the next. 

fnam designation|type 
presents a file selection box. designation  will appear as a headline, type is a specification like  P-*.?PR or c:\\allegro\\*.*. This is to control the names to be shown and the path on which to start. If this is missing, all files are shown. Use if no to check if nothing was selected. The selected name will afterwards be in the  iV,  as ac omplete path name. Use a subsequent  open  to open it for reading. 

form i
Activate form  i  (i = 1...)  (in the sequence of the .FRM file) . The FLEX stops at this point and resumes after the form is closed.
Several  such commands can be executed in succession. 
Instead of a number  i one can use the headline of a form as found in the .FRM file. 

get    acon
	Read next line from the open file  (see  open)  into the iV, to use in subsequent command.

help name
name is the name of an RTF file (without the .rtf) which will then be displayed in the display window. Same as an h flip. Instead of an RTF it can be a simple ASCII file. The program then uses HELPHEAD.RTF as a standard header to enable the display - the appearance being rather plain because of the lack of RTF markup in the ASCII file. 
If .RTF is appended to the name, any embedded flips will also become visible. these are lines beginning with a ? and following the schema: 
?FlipText=Flip command 
Somewhere within the text one must then have a string that matches FlipText and is enclosed in square brackets or between two codes  160 (to be input by Alt+0160). 

if #nnn command   acon
if not #nnn command   acon
If field  #nnn is present / not present in the current record, execute command . 
This will often be a  jump  command, but it can also be a sequence of other commands, separated by a semicolon. Instead of #nnn, there can be a #uxy variable, a $ variable or a persistent variable. The test is always for their existence, that means if there is a value attached to the name of the variable. All variables contain text. There can be no empty variables.
The  if  command is among the most used ones, and it knows many more options for testing.

index |i abc
Show index i at position  abc,  for example:   index |1 shakesp 
The FLEX will resume after the index is closed. Several such commands can therefore be executed in succession, with other commands interspersed. 

input n
This changes the number of the file to be used for saving new records. No visible reaction. 
The access=  level set in the INI file must be at least 2. 

insert #xyz    acon
Copy the content of the iV to field #xyz . Instead of a datafield #nnn, it can be a user variable #uxy or a $-variable. 

insert $a+#xyz    acon
Append the iV as subfield  $a to #xyz 
insert $a-#xyz    acon
Replace subfield $a, if it exists, otherwise add it to #xyz. If the iV is empty: subfield $a will be deleted 

jump label   acon
Processing goes on at position marked by :label 

Jump xTEXT
like "display", but using the current export parameters (section #-x therein)  instead of the display parameters. TEXT will then be in variable #u1 
Output via  export  commands (q.v.) is more reliable. 

load 
to be used after   choose ... (q.v.) 
The selected record is fetched and made the current record. Another  load reloads the previously active record. 

message Text
Text is displayed in a message box;  [OK] must be pressed. 
If the user is to be asked for a decision: use   yesno
If the user is to be prompted for an input: use    ask
new    acon
A new, empty record is created. The current record in its current state is copied to the offline file as well as to the reserve store (background store). Manual input may follow, or #- and insert commands, or transfer, to copy fields from the reserve! 
next / next #   acon
The next result set record (in the current sequence) / the next database record in the internal sequence  is loaded. 
FLEX ends if the current record is the last record. 

open name   acon
Open file  name  for reading (with commands  get  and  fetch ) 
iV content will be used for a  name  if none given.

order M P   acon
Order (sort) the result set using the short title list entry 
M = Modus: a=ascending, d=descending, n=by internal record number 
P = Position in the short title entry: the first position is 0 

pipe program   acon
Start the  program  and then read from its output using  get.
program  may be any internet address, and the output is the HTML content it delivers
 
prev / prev #   acon
The previous record is fetched from the result set, and displayed. 
FLEX ends if the current record is the first record. 

print 
Print the display window's content (as with the print button) 
 
Put 	Save current record, but ask the user first  
put	Save without asking.    acon

Put new
put new   acon
Save current record as a new record.   copy\put would do the same.) 
If  it was an online record, the result will then be a duplicate. 

read    acon
Read file E.ADT and merge into current record. E.ADT can contain any list of fields. This is an aid for data input) 
In  acon , the command reads the next record from the file opened with the first  read  command:  read filename

select prompt=response1|resp2|resp3|...
Present the list of responses for selection. The selection will be copied to the iV. If + precedes the prompt , the selection is appended to the iV. See also  load

select prompt=#usp.
 #usp must contain the list of responses, separated by | .
select #usp.
#usp must contain the prompt and the list of responses. 

set ...     acon
A command with many options! Two of them are these: 

set pX     acon
A subsequent  update  command will use section #-X in the index parameters to determine the primary key. 

set uxyz    acon
Set the update modes  x and y as in DOS-UPDATE, 
z=0: No direct saving of updated and new records but copy them to the offline file.

show xxx
Control the listbox (left hand side).  For xxx : 
res   		Reserve store 
rec     		fields of current record 
sets        		result sets 
cfg          		Configuration 
 
sleep n    acon
Wait n milliseconds before going on. (For 3 seconds one would have to write: sleep 3000) 
For example, use this when displaying a sequence of help pages and/or index sections. Add yesno commands to make it more flexible: 
help name1\sleep 4000\yesno Go on?\help name2\sleep 4000... 

transfer #nnn 
Copy field #nnn from background into current record. 
If, however, a variable #uxy is to be copied into a field:  var #uxy\ins #nnn

undo 
Same as button  [Old/New] : Toggle between edited and original form of current record. 

update     acon
These functions work the same way as in  acon, the console program for offline job execution. 
upload     acon
The DOS program UPDATE can be replaced by these functions. Different from UPDATE, the process can be monitored interactively. Unlike UPDATE, not just type .ALG files can be uploaded but also (as with acon) the simpler externam format (type .ADT). 

variable mixed string    acon
The  mixed string  is copied into the iV. The string uses the same syntax as with the    write command (see below) 
This is the most-used command since with it, every string needed for operations must be put together. The string is in the iV after this command, and the next command will use it for its operations. 

variable +mixed string    acon
The + option append the string to the iV rather than overwriting it. This way, one can construct any combination of field contents and constant elements, for example 
var #40 ": " #20          copy contents of #40 and #20 to iV , separated by ": " 
var +" (" #76 ")"        append (content of #76) to the end of  iV 
ins #upt                 store iV in #upt  (The iV as such remains intact!) 

write iV     acon
Write contents of iV (a mixed string composed by a preceding  var  command) to the output file, without changes. 

write  mixed string         acon
This is the fastest way to write field contents and any other text directly into the output (export) file. 
Additionally, the mixed string is copied to the iV. 
Example: 
write "Title: " #20 n "Author: " #40 n "Place: " #74 " (" #76 ")" 
this will produce output like this: 
 
   Title: Hamlet 
   Author: Shakespeare, William 
   Place: London (1982) 

The  n  is shorthand for  newline. 
Simple exports can be done this way, like with acon, without using the export language. 
Beside the n, there are many more shorthand variables for all sorts of internal values,  like t  for the total number of records and i for the internal number of the current record. 

yesno question
noyes question
The question appears in a Yes/No-Box. The user has to reply before the program continues. 
"No" stops the FLEX, i.e. aborts its execution. 
With "noyes" the [No] button instead of the [Yes] button is the default - [Enter] then means No. 

zzz	No command - noeffect      acon

What is a mixed string?  (see commands variable and write) 
That's any chain of elements, of several types, separated by spaces: 

"xyz"	Character string, enclosed in "..."  or '...' 
d d d  	ASCII codes as decimal numbers (e.g.,  27 69  for  Esc  E) 
#nnn 	field tags   (#nnn may also be a #u variable or a special field like #dt (see handbook)) 
#nnn$a	Subfield (only the subfield content will be written) 
#nnn$a	Subfield (only the subfield content will be written) 
#uxy 	#u variables (as used in export parameters)
#uxy$a	subfield $a of the #u variable
$name	Named "free" variable (name of arbitrary length)
&name	Persistent variable - outlives the job - available in subsequent jobs

Special internal variables:
 i 	internal number of record 
 l 	Length (size) of result set 
 n  	new line 
 p 	Primary key of current record 
 r 	relative position number of record in result set 
 s 	Short title line of record (from .STL file) 

FLEX Examples 

Example 1 : Partially automatic editing of a record 
This is the task: Records are to be retrieved by their inventory number, one particular field has to be added or edited, then save the record back - or sometimes not. 
Assumption: there's an section INV within index 9 containing the inventory number. 
This can be done by a FLEX like the following: 

  Prompt the user for the next inventory number (Default: content of #uib) 
   when user presses the index button of the ask input box, this should bring up index 9 
ask  |9Inventory number=#uib 
  The number entered goes into the iV, copy it to #uib : 
ins #uib 
  Now compose the internal variable from "inv " and #uib 
var "inv " #uib 
  and execute this as a find command (i.e., "find inv nnn") 
find 
  Insert field #xyz containing  Text into current record
#xyz Text
  ask user if the record is to be saved 
yesno Save? 
  and do this if the  "OK" button was pressed 
put 
  Put  can be used instead of the last two commands, for this also asks for confirmation 

Example 2 : Input assistance 
New records are to be provided with a number of predefined fields. Enter into the write field: 

#uX3x new\#nn1 Text1\#nn2 Text2\#nn3 Text3\trans #nn4\form 2 

First, a new (empty) record is created, then three predefined fields are inserted, field #nn4 is copied from the reserve store, then form 2 is activated for further input.  Alt+3 activates this FLEX. This example is easily extended. 
Several such FLEXes can be created for different types of records. 

?Functions Overview=x var P "help\\flexeng.vw"\View 
?Alphabetic Index=h xa 
?ask=h xask 
?variable=h xvar 
?yesno=h xyes 
?message=h xmessage
?German list=h flexger