allegro FLEX : Compact Command Table for acon

Full German FLEX documentation is available in the Windows a99 help system as well as at http://www.allegro-b.de/downloads/doku/flex/.
This is a brief summary of just those commands that can be used for FLEX scripts executable by the console program acon.
To understand what follows, it is important that you recall what's said in the acon introduction about the internal Variable (iV).

Rule of three: For every command word except "erase", only the first three letters are significant, the rest is optional and simply ignored.
The table shows three properties with every command: ( x indicates that the command does have the resp. property)
y/n     Success / Failure can be checked with  if yes / if no  on the next line.
              In some cases, other conditions are possible: if cancel  etc.
iV in    If there is no argument right after the command, it will use the content of the internal Variable (iV) instead
iV out  The command will write its result into the iV for immediate use in the following line, using one of the commands with x in "iV in"
These are only the commands known to acon. For a99, there are quite a few more, mostly for interactive functions. Note that the only interactive command for acon (waiting for user input) is ask.  

Don't hesitate nor be afraid to try everything out on the demo database!
Replace words in italics by appropriate text or, e.g., file names

Command line y/n iV in iV out What it does
// comment line is comment. No effect. (line is actually stripped out while reading the job file.)
_A_B_  |  ,A,B, Replace string A with string B everywhere in the current record; use '_' if a ',' occurs in A or B and vice versa
ansi | asci x x Use the o table (index param) to convert iV content from ASCII to ANSI (Windows code) or reverse
ask question x x Put the question to the user and wait for input; check it with  if ..., save it with  insert ...
call program x Start another program and wait until it terminates (see also  pipe
check
x
 x
 Checks if the iV text begins with a valid field tag. If not, then iV contains two spaces + error msg.
check f x x Additional check for invalid subfield codes
close x

Close the file previously opened for reading (open file)
close x x Close the file previously opened for writing (open x file)
copy Copy current record to make it a new one. Then, modify with insert..., eventually save it with  put
crypt x x Encrypt the iV content irreversibly [used in authorization procedures, for instance for a35]
var | write cstring Character string composed out of data fields, literal text, and variables; use only with var and write!
date | day | Day +/-n  x x Today's date YYYYMMDD/hh:mm:ss | day +0 = Nr. of day within year | Day +n = current date +/- n days
dir pattern x x List of filenames that fit a pattern, iV then contains names separated by 2 spaces
end Terminates the job. There may be more than one  end  in the job
erase x Deletes the current record (do not abbreviate the word 'erase' )
eval expression x x Evaluate expression as a formula to calculate its numeric value (which then appears in iV)
export x Export current record using currently loaded export parameters, write into currently open export file
export file fname x x Open file fname as export file
export param pname x x Load parameter file  pname.xpr  for export (x : CFG letter, from filename x.cfg)
family Collect all records linked to the current record into a result set
fetch x x Reads specified number bytes or a data record from external previously opened
find findcmd x Execute a find command to build a result set. Check for failure with  if empty ...
f1nd findcmd x x Same, but then immediately load the first record of the result set
first | first # Load first record of current result set (of latest  find)  |  first record of database (internal nr. 1)
fsize filename x x x Does the file exist? if yes, its size will be in the iV
get x x Read next line from file previously opened with  open file. Check for end with  if cancel ...
get env name x x x Get environment variable  name  into iV
get Iurl x x Get textual content of internet address  url  into iV. Check for failure with  if cancel ...
Files of up to 4MB size, from anywhere in the Internet, can be loaded into  iV  this way!
hyphen x x hyphenates the iV content if it is an ISBN without hyphens
if condition comstring Check the condition, and if it holds, execute the comstring (commands separated by ;)
Which conditions can be checked depends mostly on the preceding command, see full documentation

include file
 
THIS IS NOT A COMMAND, but this line is replaced by content of file before the job gets executed.
insert vname x Copy iV content into a variable; if iV empty, remove variable.
vname= #nnn, $x-#nnn (for subfield $x in #nnn), #uxy, $abc, &xyz
insert $ | var $ x x Special case: Make an exact copy of the iV  |  Copy that copy back into the regular iV
insert _A_B_  or  
insert ,A,B,		 x x Special cmd: Replace substring A everywhere in iV content by string B (use , if _ occurs and vice versa)
jump mark x Jump to the line beginning with :mark and proceed with the line following it
katlist x Write the field definition list from the CFG file into the iV (just the tags and field names)
last | last # Load last record of current result set (built earlier)  |  last record of database (highest internal nr.)
list Write short title list of result set into the output file; if none open, to the console
new Empty the record space out to create a new record. Proceed filling it with insert statements or a read 
Before this, be sure to  save  the current record if there was any change
next 
next #		 x Load next record of current result set
Load next record of database (next internal number after current rec.)
open file
open x file		 x x Open the file for reading with  get  or  fetch, check for failure with  if no ...
Open the file for subsequent writing with  write  or  export
order MP Order the result set, using text position P of the .STL entries; M : A = ascending / D = descending
perform label x Jump to line after the :label, return as soon as a  return  statement is encountered.
pipe program x Start program and read its output line by line with get. Check for termination with  if cancel ...
prev | prev # x Load previous rec. of current result set  |  previous rec. of database (internal number before current rec.)
put x Save the current record to the database (includes all necessary indexing work and/or relocation)
qrix | Qrix x Write part of index into export file | into iV (lines separated by Code 20 = ^T).
Check for failure with if "" ...
read file 
read		 x Open  file  for reading and read first record
Read next record (put before the next read to save record if changed)
return Terminates a subroutine. Continue with line after perform (from where the subr. was called)
set / switch x x There's a large range of properties that can be controlled with this command, incl. locks
sleep m Do nothing for m milliseconds (sleep 1000  for 1 second)
sort MP x Sort lines (separ. by Codes 13 10) in the iV (up to 4MB), at position P
spaces x x Eliminate multiple spaces from the iV text (may be useful after a read)
srx regex x Check for occurrence of regex (regular expression) in the iV text. If regex not given, use string in  #u!! 
sub #0i nnn x x If current record is a hierarchical one, switch to subrecord headed with #0i nnn  (i = 1,2,...,6)
update file Read file , containing records to update the database with. Befor this, use  set uxy  to set the mode.
upload file Same, but with  mode  u01 (treats every record as a new record, no matching with existing ones)
var cstring x x Interpret the cstring to compose a text string that will then replace cstring to be used by the next command
var Ffile x x Special case of  'var' : Get the entire file (max. 4 MB) into the iV
write cstring x x Same syntax as with var, but writes cstring into the output file (default: console) instead into the iV
write iV Special case: write the iV content as is, without any changes
xcode x x Use code tables to convert the iV text.
Esp.  xcode u  turns UTF-8 into internal code (requires table  ucodes.apt)
Write cstring x Same as write, but output to the console in all cases
xchange _abc_xyz_ x x Search for abc and replace by xyz in the iV content
xml x Convert the current record into different variants of XML formatted text using the CFG field names
z | Z  = + - * / x Do elementary calculations with the values of z or Z (two special variables, see below) and the iV content

The last line refers to an unusual shortcut calculation device:
z is an integer, Z is a decimal number, both initially 0.  (There are just z and Z, you cannot replace them by any other name!)
If we have, at some point in a job,  z = 25  and  Z = 14.2345, and the iV contains  "15.2", then
z +   will result in  z = 40   (rounded! since z is an integer)
Z -   will result in  Z = -0.9655
These values can be accessed anytime in a job, by writing  var z  or  var Z, and also in write statements.
Furthermore, if  statements can use the two values for comparisons. For example:
if z = 10 jump xyz
if Z > 1.345 jump abc
For plain counting and summing up, these special variables are convenient tools.
In other cases, and when there is need for more than just two variables, one will use "proper" variables ($name or #uxy variables mostly) and the  eval  command to do calculations:  eval #nnn$k + $abc - 2.5 / #uxy  performs the  evaluation from left to right, using the numeric values of the variables or constants.

cstring - Syntax for the composition of character strings
The commands  var  and  write, (but only these!) can be used to compose character strings using this concept.
First, some examples, assuming we have a MARC-like internal record format (3-digit field tags):
cstring Result Remark
"This database has " t " records" This database has 125436 records   t = total number of records
"ISBN: " #020 ISBN: 0-674-63711-9 #020 = MARC Field tag for ISBN
"Date published: " #260$c Date published: 1997 #260 = Field for imprint, subfield $c = date
$Text (b"Title: " e"^M^J") Whatever follows after "Title: " in $Text If $Text contains line formatted data, lines end in Codes 13 and 10
"Record " i ":" n kr Record 123: newline internal text of record i = internal nr of current record

Several different types of components can be freely combined, space-separated, to form a text string of any length (up to 4 MB):
"literal text"  or  'literal text' :  non-printable characters coded as, e.g., ^J for code 10 (line feed). That's two characters: ^ and J.
#nnn    :   Content of field #nnn of current record
#nnn.   :  Content of the first of several fields #nnnx  in current record
#nnn$x :   Content of subfield $x of field #nnn of current record
_nnn    :   Content of field #nnn including the number nnn

The  nnn  may also be the name  uxy  of a user variable (export language)
Enclosed  in (...), a manipulation command string can be appended to #nnn

$xyz : Content of the "free variable" $xyz
Enclosed  in (...), a manipulation command string can be appended to $xyz but with a space in between $xyz and (, like  $Text (b"Title: " ...)

&xyz : Content of the "persistent variable" &xyz  (stored in the "special index" file  dbname.xzx = copy of cat.azx of demo database)

Besides all these, there is a large number of special variables, most of them represented by a single letter (like t and i in the examples above), that can be freely interspersed between literals and variable names. The job  al.job  shows all the special variables with their current values: use the function  "admin / settings".

B.Eversberg, 2014-08-12 / 2020-11-24