allegro FLEX : Compact Command Table for acon

Rule of three: For every command word except "erase", only the first three letters are significant, the rest is optional and simply ignored.
To understand what follows, it is important that you recall what was said in the introduction about the "internal Variable" (iV).
There are three properties with every command:

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 present following 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.  Full German documentation is available as part of a99 help texts.
Don't hesitate nor be afraid to try everything out on the demo database!

Command y/n iV in iV out What it does
// comment A line of comment. No effect. (These lines are 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 ',' 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 )
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]
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, 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
eval expression x x Evaluate expression as a formula to calculate its value
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 Reads bytes or data records from external files
find findcmd x Execute a find command to build a result set. Test 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 ...
if condition comstring Check the condition and if it holds, execute the comstring (commands separ. by ;)
include jobfile THIS IS NOT A COMMAND, but this line is replaced by content of jobfile before the job is executed
insert vname x Copy iV content into a variable; if iV empty, remove variable. vname= #nnn, $x-#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  ,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 
next | next # x Load next record of current result set  |  next record of database (next internal number after current rec.)
open file x x Open the file for reading with  get  or  fetch
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). 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 it)
return Terminates a subroutine. Continue with line after perform (from where subr. was called)
set 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 Sort lines (separ. by Codes 13 10) in the iV (up to 4MB)
spaces Eliminate multiple spaces from the iV text
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 fill the iV for further action
var Ffile x x Special case: Get the entire file (max. 4 MB) into the iV
write cstring x x Same syntax as var, but writes cstring into the output file (default: console) instead into the iV
write iV Special case: write the iV content out with no interpreatation as cstring or code changes
xcode x x Use code tables to convert the iV text. Esp.  xcode u  turns UTF-8 into internal code (req. 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  = + - * / 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, as 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 = Field tag for ISBN
"Date published: " #260$c 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