Subsections

a68toc extensions

The a68toc manual describes the language restrictions of the translator. Chapter 3 contains details of the FORALL construct. This section is intended to document those extensions used in the QAD standard prelude.

Modes peculiar to a68toc

The principal extensions to Algol 68 modes are the introduction of multiple modes whose housekeeping overhead is less than the standard row modes.

  1. STRUCT n MODE
    This mode is called an “indexable structure”. The n, a non-negative integer, is built into the mode and must be an integer denotation. The base mode can be any mode. It is equivalent to a C language “array”. Here is a list of modes used in the QAD standard prelude which are either indexable structures or references to such:-
    1. CSTR=REF STRUCT 16000000 CHAR
      This is a reference mode and is equivalent to the C type char *. It is used in the ALIEN (see section 12.3.4) definitions of linux getenv, for example, to reference data.
    2. CCHARPTRPTR=REF STRUCT 16000000 CSTR
      Again, this is a reference mode and is equivalent to the C type char **. It is used to access the program's arguments.
    A considerable number of operators use indexable structures for converting values of one mode to another using memory mapping (see section 13.5.3.
  2. VECTOR[n]MODE
    The VECTOR mode has less overhead than a row mode because its lower bound is always one. It is commonly used to provide strings to C procedures. The following modes are defined using VECTOR:-
    1. STR=VECTOR[0]CHAR
      Due to the way in which C multiples are defined (without bounds), the mode STR can be used for any length VECTOR.
    2. RVC=REF STR
      This mode is used in a number of operators, such as
         OP MAKERVC = ([]CHAR s)RVC:
      
      It is also used to construct other modes such as BOOK (see section 13.7).
  3. Coercions provided by a68toc
    A value of mode STRUCT n MODE can be coerced directly to a value of mode VECTOR[]MODE. Likewise, a value of the latter mode can be coerced to a value of mode []MODE. Therefore, preferably use the mode []MODE for a parameter to a procedure.
  4. Other modes used by a68toc
    Some modes are provided to make interfacing with C library procedures easier. Here are the ones provided by the QAD standard prelude:-
    1. CPTR=REF BITS
      This mode is equivalent to the C type void *.
    2. CINTPTR=REF INT
      Equivalent to the C type int *.
    3. CCHARPTR=REF CHAR
      Equivalent to the C type char *.
    4. GCPARAM=STRUCT(STR name,INT value)
      Used to access parameters of the garbage-collector (see section 13.6.3 below).
    5. PDESC=STRUCT(CPTR cp,CSTR env)
      This represents the structure created by a68toc for every Algol 68 procedure. The field cp contains the actual memory address of the procedure and the field env contains data used by the procedure.
    6. VDESC=STRUCT(CCHARPTR data,BITS gc,
      INT upb)
      This mode represents the housekeeping overhead of a VECTOR. The data field is the actual memory address of the start of the data and the upb field is the upper bound of the vector. The gc field is used by the garbage-collector (the heap manager).

a68toc constructs

This section describes those constructs which are either peculiar to a68toc or which are in some way different from standard Algol 68.

  1. FORALL
    FORALL is described in section 3.10.
  2. ALIEN and CODE
    Both ALIEN and CODE are described in the a68toc manual. ALIEN is also described in section 12.3.4. All ALIEN declarations used in the QAD standard prelude appear in the file spaliens.a68 which you should consult for further details. You should note that the ALIEN declarations were established by trying various modes until a definition was found which a68toc translated to a compilable C source file.

    As described in the a68toc manual, source files may contain either a PROGRAM module or a DECS module. The latter may contain declarations and CODE clauses only. See the file transput.a68, lines 1185-92, for an example of how to execute code when a DECS module is being elaborated.

  3. USE lists
    The USE list of a DECS or a PROGRAM module generates calls to the relevant initialiser PROCs (see the generated C file for standard.a68 for an example) in the reverse order of the given modules. Therefore, if the order matters, ensure that the USE clause mentions each module in the proper order.
  4. The BY construct in a FOR loop
    Unfortunately, the BY construct in a FOR loop (see section 3.7) generates an internal compiler error if it is followed by an integer denotation or a formula consisting of + followed by an integer denotation. This is a definite bug. The remedy is to use a simple procedure or operator or the denotation preceded by two minus symbols. For example, instead of writing
       FOR i BY 5 TO ...
    
    use
       FOR i BY --5 TO ...
    
  5. The default case in a CASE clause

    If in a CASE clause, whether a simple CASE or a conformity CASE clause (one which determines the mode of the value in its enquiry clause), the default clause can occur, then you must include at least OUT SKIP, otherwise you will get a run-time fault.

  6. BIOP 99
    In Algol 68, a UNION (see section 8.1) is a well-defined mode composed of constituent modes. A value of one of the constituent modes may be assigned to a name of the united mode and only that value (with its original mode) can be extracted. In the C language, however, a “free union” or just “union” is a piece of memory which can have different interpretations. The BIOP 99 construct enables the operand of an operator using it to be re-interpreted as a value of the mode given in the yield. for example, the operator FLAT declared as
       OP(REAL)STRUCT 8 CHAR FLAT = BIOP 99;
    
    accepts a REAL parameter which, as the yield, is regarded as an indexable structure of 8 characters each of which can be accessed separately. See section 13.5.3 for operators using this construct.

Operators

These are largely operators using the BIOP 99 construct, but there are a number of other operators which ease the task of interfacing with C library procedures.

Operators using BIOP 99

Most of the operators used in the QAD standard prelude which are defined using the BIOP 99 construct are for internal use only. In the following list, the full declaration

   OP(CPTR)CSTR TOCSTR = BIOP 99;
is abbreviated to
   OP TOCSTR=(CPTR)CSTR:

Here is a list of operators using the BIOP 99 construct which are made available by the QAD standard prelude:-

  1. OP FLAT=(REAL)STRUCT 8 CHAR:
  2. OP FLAT=(SHORT REAL)STRUCT 4 CHAR:
  3. OP FLAT=(STRUCT 8 CHAR)REAL:
  4. OP FLAT=(STRUCT 4 CHAR)SHORT REAL:
  5. OP FLATB=(LONG BITS)STRUCT 8 CHAR:
  6. OP FLATB=(BITS)STRUCT 4 CHAR:
  7. OP FLATB=(SHORT BITS)STRUCT 2 CHAR:
  8. OP FLATB=(SHORT SHORT BITS)STRUCT 1 CHAR:
  9. OP FLATB=(STRUCT 8 CHAR)LONG BITS:
  10. OP FLATB=(STRUCT 4 CHAR)BITS:
  11. OP FLATB=(STRUCT 2 CHAR)SHORT BITS:
  12. OP FLATB=(STRUCT 1 CHAR)SHORT SHORT BITS:
  13. OP CCHARPTRTOCSTR=(CCHARPTR)CSTR:
    This operator is used to define the on exit procedure.
  14. OP CSTRTOCCHARPTR=(CSTR)CCHARPTR:
    This operator converts in the opposite direction.
  15. OP TOCPTR=(INT)CPTR:
  16. OP TOCSTR=(CPTR)CSTR:
  17. TOPDESC=(PROC VOID)PDESC:
    This operator provides a means of getting the address of a procedure and is used to provide the identifier of an Algol 68 procedure which must be elaborated by an ALIEN procedure (such as a C library routine).
    OP TOPDESC=(PROC(INT,CPTR)VOID)PDESC:
    OP TOPDESC=(PROC(INT)VOID)PDESC:
    OP TOPDESC=(PROC(INT,RVC)PDESC:
    You can define as many TOPDESC operators as you wish with operands of procedures you will need. You will certainly need more definitions of TOPDESC if you write wrapper procedures for X Window System procedures which have procedural parameters. See the file transput.a68 for details of how this operator is used.
  18. OP TORPDESC=(REF PROC VOID)RPDESC:
    This operator converts a reference to a PROC VOID to a reference to a value of mode PDESC.
  19. OP TOVDESC=(STR)VDESC:
    This operator provides a means of getting the address of the STR in a form suitable as a parameter to C library routines.
  20. OP TOVBDESC=(VECTOR[]BITS)VBDESC
    This operator provides a means of getting the address of the VECTOR[]BITS.
  21. OP TOVIDESC=(VECTOR[]INT)VIDESC
    Exactly as for the previous routine, but for a VECTOR[]INT.

Other operators

Here is a list of operators not using the BIOP 99 construct:-

  1. OP CPTRTORVC=(CPTR)RVC:
    Used to cast the C type void * to the type char *.
  2. OP CSTRTORVC=(CSTR)RVC:
    Converts a C string to an RVC using the standard RS Algol 68 coercion
       REF STRUCT n CHAR => REF VECTOR[]CHAR
    
    It is mainly used to access C strings yielded by C library routines. The parameter must be terminated by a null character.
  3. OP FLATRVB=(RVC)BITS:
    Converts a VECTOR[4]CHAR into a BITS.
  4. OP FLATRVLB=(RVC)LONG BITS:
    Converts a VECTOR[8]CHAR into a LONG BITS.
  5. OP FLATRVSB=(RVC)SHORT BITS:
    Converts a VECTOR[2]CHAR into a SHORT BITS.
  6. OP FLATRVSSB=(RVC)SHORT SHORT BITS:
    Converts a BECTOR[1]CHAR into a SHORT SHORT BITS.
  7. OP FLATRVR=(RVC)REAL:
    Converts a VECTOR[8]CHAR into a REAL.
  8. OP FLATRVSR=(RVC)SHORT REAL:
    Converts a VECTOR[4]CHAR into a SHORT REAL.
  9. OP MAKERVC=(CHAR)RVC:
    OP MAKERVC=(STR)RVC:
    OP MAKERVC=([]CHAR)RVC:
  10. OP VBTOCPTR=(VECTOR[]BITS)CPTR:
    This operator gets the address of the VECTOR[]BITS in a form suitable as a parameter to a C library routine.
  11. OP VCTOCHARPTR=(STR)CCHARPTR:
    Yields the C pointer from an a68toc descriptor. If a C string is expected, a null character must be appended to the data before the routine is called. This need not be done for string denotations. This routine may be used to yield a C pointer from an RVC, as the C representation is the same.
  12. OP VITOINTPTR=(VECTOR[]INT)CINTPTR:
    Yields the address of the VECTOR[]INT in a form suitable for use as a parameter of a C library routine.
  13. OP STRTOCSTR=(STR)CSTR:
    The operator combines the action of the operators CCHARPTRTOCSTR and VCTOCHARPTR.
  14. OP Z=(STR str)STR:
    Yields a null-terminated STR from a STR for use with the C library.
Sian Mountbatten 2012-01-19