AINSERT instruction

Edit online

The AINSERT instruction inserts records into the input stream. If it is used in a macro, the records are queued in an internal buffer until the macro generator has completed expanding the current outermost macro instruction. At that point the internal buffer queue is inserted into the input stream, so that it provides the next record or records. If AINSERT is used in open code, the buffer queue only contains one record, which is inserted immediately after the AINSERT instruction. An operand controls the sequence of the records within the internal buffer queue.

Note: You can place inserted records at either end of the buffer queue, the records are removed only from the front of the buffer queue.
Read syntax diagramSkip visual syntax diagramsequence_symbolAINSERT'record',BACK,FRONT
sequence_symbol
Is a sequence symbol.
record
Is the record stored in the internal buffer. It can be any characters enclosed in apostrophes.
The rules that apply to this character string are:
  • Variable symbols are allowed.
  • The string can be up to 80 characters in length. If the string is longer than 80 characters, only the first 80 characters are used, the rest of the string is ignored.
BACK
The record is placed at the back of the internal buffer.
FRONT
The record is placed at the front of the internal buffer.
Notes:
  1. The ICTL instruction does not affect the format of the stored records. The assembler processes these records according to the standard begin, end, and continue columns.
  2. The assembler does not check the sequence field of the stored records, even when the ISEQ instruction is active.
  3. Continuation is ignored for the last record in the AINSERT buffer but is active for all other records.
  4. After the buffer queue has been inserted into the input stream, any further AINSERT instruction starts a new buffer queue. This is inserted at the appropriate point in the input stream, which may be before the remaining records from a previous inserted buffer queue.
  5. Processing of each inserted buffer queue is terminated either when input processing reaches the end of the queue or when a conditional assembly branch is taken to a sequence symbol before or after the point at which the queue was inserted. At this point, any unprocessed source code in the queue or included members is discarded, and any sequence symbols defined by the inserted or included code are deleted. It is not possible for conditional assembly to branch back into the inserted source code.
  6. Records in the AINSERT buffer queue are not visible to lookahead processing until it has been inserted into the input stream. However, the AREAD instruction takes input records from the AINSERT buffer queue before reading the input stream.
Example: 
         MACRO
         MAC1
         .
 .A      AINSERT 'INSERT RECORD NUMBER ONE',FRONT       Insert record into the input stream
 .B      AINSERT 'INSERT RECORD NUMBER TWO',FRONT       Insert record at the top of the input stream
 .C      AINSERT 'INSERT RECORD NUMBER THREE',BACK      Insert record at the bottom of the input stream
         .
         .
         .
 &FIRST  AREAD                                             Retrieve record TWO from the top of the input stream
         .
 .D      AINSERT 'INSERT RECORD NUMBER FOUR',FRONT      Insert record at the top of the input stream
         .
 &SECOND AREAD                                             Retrieve record FOUR from the top of the input stream
         .
         MEND
         CSECT
         .
         MAC1
         .
         END

In this example, the variable &FIRST receives the operand of the AINSERT statement created at .B. &SECOND receives the operand of the AINSERT statement created at .D. The operand of the AINSERT statements at .A and .C are in the internal buffer in the sequence .A followed by .C and are the next statements processed when the macro generator has finished processing.