9.5. Duplicate with Varying Argument (ECHO)

The ECHO pseudo instruction defines a sequence of code that is assembled zero or more times immediately following the definition. On each repetition, the actual arguments are substituted for the formal parameters until the longest argument list is exhausted. Null strings are substituted for the formal parameters after shorter argument lists are exhausted. The echo sequence to be repeated consists of statements following the ECHO pseudo instruction and any optional LOCAL pseudo instructions. Comment statements are ignored. The echo sequence ends with an ENDDUP that has a matching label field name.

You can use the STOPDUP pseudo instruction to override the repetition count determined by the number of arguments in the longest argument list.

You can specify the ECHO pseudo instruction anywhere within a program segment. If the ECHO pseudo instruction is found within a definition, it is defined and is not recognized as a pseudo instruction. If the ECHO pseudo instruction is found within a skipping sequence, it is skipped and is not recognized as a pseudo instruction.

The format of the ECHO pseudo instruction is as follows:

dupname ECHO [name=argument],[[name=]argument]

The variables associated with the ECHO pseudo instruction are described as follows:

• dupname

  dupname specifies the required name of the echo sequence. It must match the label field name in the ENDDUP instruction that terminates the echo sequence. dupname must meet the requirements for names as described in Section 6.3.

• name

  name specifies the formal parameter name. It must be unique. There can be none, one, or more formal parameters. name must meet the requirements for names as described in Section 6.3.

• argument

  argument specifies a list of actual arguments. The list can be one argument or a parenthesized list of arguments.

  A single argument is any ASCII character up to but not including the element separator, a space, a tab (new format only), or a semicolon (new format only). The first character cannot be a left parenthesis.

  A parenthesized list can be a list of one or more actual arguments. Each actual argument can be one of the following:

  • An ASCII character string can contain embedded arguments. If, however, an ASCII string is intended, the first character in the string cannot be a left parenthesis. A legal ASCII string is 4(5). An illegal ASCII string is (5)4(5).

  • A null argument; an empty ASCII character string.

  • An embedded argument that contains a list of arguments enclosed in matching parentheses. An embedded argument can contain blanks or commas and matched pairs of parentheses. The outermost parentheses are always stripped from an embedded argument when an echo definition is expanded.

An embedded argument must meet the requirements for embedded arguments as described in .

In the following example, the ECHO pseudo instruction is expanded twice immediately following the definition:

LIST DUP EXAMPLE ECHO PARAM1=(1,3),PARAM2=(2,4) ; Definition. CON PARAM1 ; Gets 1 and 3. CON PARAM2 ; Gets 2 and 4. EXAMPLE ENDDUP

The following example illustrates the expansion of the preceding example:

CON 1 ; Gets 1 and 3. CON 2 ; Gets 2 and 4. CON 3 ; Gets 1 and 3. CON 3 ; Gets 1 and 3. CON 4 ; Gets 2 and 4.

In the following example, the echo pseudo instruction is expanded once immediately following the definition with two null arguments.

list dup example echo param1=,param2=() ; ECHO with two null parameters. _*Parameter 1 is: 'param1' _*Parameter 2 is: 'param2' example enddup

The following illustrates the expansion of the preceding example:

*Parameter 1 is: '' *Parameter 2 is: ''