SETC instruction

The SETC instruction assigns a character value to a SETC symbol. You can assign whole character strings, or concatenate several smaller strings together. The assembler assigns the composite string to your SETC symbol. You can also assign parts of a character string to a SETC symbol by using the substring notation; see Substring notation.

A character string consists of any combination of characters enclosed in single quotation marks. Variable symbols are allowed. The assembler substitutes the representation of their values as character strings into the character expression before evaluating the expression. Up to 1024 characters are allowed in a character expression.

You can change the character value assigned to a SETC symbol. This lets you use the same SETC symbol with different values for character comparisons in several places, or for substituting different values into the same model statement.

Read syntax diagramSkip visual syntax diagram>>-variable_symbol--SETC--character_value----------------------><
 
variable symbol
is a variable symbol.

A global variable symbol in the name field must have been previously declared as a SETC symbol in a GBLC instruction. Local SETC symbols need not be declared in a LCLC instruction. The assembler considers any undeclared variable symbol found in the name field of a SETC instruction as a local SET symbol. The variable symbol is assigned a type attribute value of U.

character_value
is a character value that may be specified by one of the following:

The assembler assigns the character string value represented in the operand field to the SETC symbol in the name field. The string length must be in the range 0 (null character string) through 1024 characters.

When a SETA or SETB symbol is specified in a character expression, the unsigned decimal value of the symbol (with leading zeros removed) is the character value given to the symbol.

A duplication factor can precede a character expression or substring notation. The duplication factor can be any non-negative arithmetic expression allowed in the operand of a SETA instruction. For example:

&C1      SETC            (3)'ABC'

assigns the value 'ABCABCABC' to &C1.

A zero duplication factor results in a null (zero-length) string.

Notes:
  1. The assembler evaluates the represented character string (in particular, the substring; see Substring notation) before applying the duplication factor. The resulting character string is then assigned to the SETC symbol in the name field. For example:
    &C2      SETC            'ABC'.(3)'ABCDEF'(4,3)
    assigns the value 'ABCDEFDEFDEF' to &C2.
  2. If the character string contains double-byte data, then redundant SI/SO pairs are not removed on duplication. For example:
    &C3      SETC            (3)'<.A.B>'
    assigns the value '<.A.B><.A.B><.A.B>' to &C3.
  3. To duplicate double-byte data, without including redundant SI/SO pairs, use the substring notation. For example:
    &C4      SETC            (3)'<.A.B>'(2,4)
    assigns the value '.A.B.A.B.A.B' to &C4.
  4. To duplicate the arithmetic value of a previously defined ordinary symbol with an absolute value, first assign the arithmetic value to a SETA symbol. For example:
    A        EQU             123
    &A1      SETA            A
    &C5      SETC            (3)'&A1'
    assigns the value '123123123' to &C5.

Subscripted SETC symbols

The SETC symbol (see  1  in Figure 42) in the name field can be subscripted. If the same SETC symbol has not been previously declared in a GBLC or LCLC instruction with an allowable dimension (see  2  in Figure 42), then the symbol is implicitly declared as a local SETC array variable.

The assembler assigns the character value represented in the operand field to the position in the declared array (see  3  in Figure 42) given by the value of the subscript. The subscript expression must not be 0 or have a negative value.

Figure 42. Subscripted SETC symbols
              LCLC     &C1,&C2
              LCLC     &SUBSCRC(20)
&D(4)         SETC     'XYZ'
              .        ^
*---  1       .        *---  2 
V             .
&SUBSCRC(10)  SETC     'ABCDE'
              .         |
              .         |
              .         |
------------------------+----------------------------------------------
                        3 -----*
&SUBSCRC Array:                |
                               V
*-----*-----*-----*----/ /----*-----*-----*-----*----/ /----*-----*
|     |     |     |           |ABCDE|     |     |           |     |
*-----*-----*-----*----/ /----*-----*-----*-----*----/ /----*-----*
^     ^     ^     ^           ^     ^     ^     ^           ^
1     2     3     4           10    11    12    13          20

Character (SETC) expressions

The main purpose of a character expression is to assign a character value to a SETC symbol. You can then use the SETC symbol to substitute the character string into a model statement.

You can also use a character expression as a value for comparison in condition tests and logical expressions. Also, a character expression provides the string from which characters can be selected by the substring notation.

Substitution of one or more character values into a character expression lets you use the character expression wherever you need to vary values for substitution or to control loops.

An attribute reference must be the only term in a character expression.

Substring notation

The substring notation lets you refer to one or more characters within a character string. You can, therefore, either select characters from the string and use them for substitution or testing, or scan through a complete string, inspecting each character. By concatenating substrings with other substrings or character strings, you can rearrange and build your own strings.

The substring notation can be used only in conditional assembly instructions. Table 60 shows how to use the substring notation.

Table 60. Substring notation in conditional assembly instructions
 
 
Used in
 
 
Used as
 
 
Example
Value
assigned to
SETC Symbol
SETC instruction operand
Operand
 
Part of
operand
&C1  SETC  'ABC'(1,3)
 
&C2  SETC '&C1'(1,2).'DEF'
ABC
 
ABDEF
AIF or SETB instruction operand (logical expression) Character value in comparand of character relation
    AIF   ('&STRING'(1,4) EQ 'AREA').SEQ
&B  SETB  ('&STRING'(1,4).'9' EQ 'FULL9')
---

The substring notation must be specified as follows:

'CHARACTER STRING'(e1,e2)

where the CHARACTER STRING is a character expression from which the substring is to be extracted. The first subscript (e1) shows the position of the first character that is to be extracted from the character string. The second subscript (e2) shows the number of characters to be extracted from the character string, starting with the character indicated by the first subscript. Thus, the second subscript specifies the length of the resulting substring.

The second subscript value of the substring notation can be specified as an asterisk (*), to indicate that all the characters beginning at the position of the first expression should be used. The extracted string is equal to the length of the character expression, less the number of characters before the starting character.

The character string must be a valid character expression with a length, n, in the range 1 through 1024 characters. The length of the resulting substring must be in the range 0 through 1024.

The subscripts, e1 and e2, must be arithmetic expressions.

When you use subscripted variable symbols in combination with substring notation, take care to distinguish variable subscripts from substring-operation subscripts.

       LCLC   &DVAR(10),&SVAR,&C(10)
&C(1)  SETC   '&DVAR(5)'            Select 5th element of &DVAR
&C(2)  SETC   '&SVAR'(1,3)          Select substring of &SVAR
&C(3)  SETC   '&DVAR(5)'(1,3)       Select substring of &DVAR(5)
&C(4)  SETC   '&SYSLIST(1,3)'(1,3)  Select substring of &SYSLIST(1,3)
Evaluation of substrings

The following examples show how the assembler processes substrings depending on the value of the elements n, e1, and e2.

Figure 43 shows the results of an assembly of SETC instructions with different substring notations.

Figure 43. Sample assembly using substring notation
  Loc  Object Code    Addr1 Addr2  Stmt   Source Statement                                  HLASM R6.0       2008/07/11 17.48
                                      8 &STRING  SETC  'STRING'                                                 00008000
                                      9 &SUBSTR1 SETC  '&STRING'(0,4)                                           00009000
** ASMA093E Substring expression 1 less than 1; default=null - OPENC
                                     10 &SUBSTR2 SETC  '&STRING'(7,4)                                           00010000
** ASMA092E Substring expression 1 points past string end; default=null - OPENC
                                     11 &SUBSTR3 SETC  '&STRING'(3,0)                                           00011000
                                     12 &SUBSTR4 SETC  '&STRING'(3,-2)                                          00012000
** ASMA095W Substring expression 2 less than 0; default=null - OPENC
                                     13 &SUBSTR5 SETC  '&STRING'(3,4)                                           00013000
                                     14 &SUBSTR6 SETC  '&STRING'(3,5)                                           00014000
** ASMA094I Substring goes past string end; default=remainder
                                     15          END                                                            00015000

You can suppress the ASMA094I message by specifying the FLAG(NOSUBSTR) option or by setting the ACONTROL FLAG(NOSUBSTR) value. When this is done, the listing changes (Figure 44).

Figure 44. Sample assembly using substring notation with messages suppressed
  Loc  Object Code    Addr1 Addr2  Stmt   Source Statement                                  HLASM R6.0       2008/07/11 17.48
                                      7          ACONTROL FLAG(NOSUBSTR)
                                      8 &STRING  SETC  'STRING'                                                 00008000
                                      9 &SUBSTR1 SETC  '&STRING'(0,4)                                           00009000
** ASMA093E Substring expression 1 less than 1; default=null - OPENC
                                     10 &SUBSTR2 SETC  '&STRING'(7,4)                                           00010000
** ASMA092E Substring expression 1 points past string end; default=null - OPENC
                                     11 &SUBSTR3 SETC  '&STRING'(3,0)                                           00011000
                                     12 &SUBSTR4 SETC  '&STRING'(3,-2)                                          00012000
** ASMA095W Substring expression 2 less than 0; default=null - OPENC
                                     13 &SUBSTR5 SETC  '&STRING'(3,4)                                           00013000
                                     14 &SUBSTR6 SETC  '&STRING'(3,5)                                           00014000
                                     15          END                                                            00015000

Character (SETC) expressions can be used only in conditional assembly instructions. Table 61 shows examples of using character expressions.

Table 61. Use of character expressions
Used in Used as Example
SETC instruction Operand &C SETC 'STRING0'
AIF or SETB instruction Character string in character relation AIF ('&C' EQ 'STRING1').B
Substring notation First part of notation 'SELECT'(2,5) returns 'ELECT'
Built-in functions Operand
&VAR  SETC  (LOWER '&twenty.&six')
&AB   SETA  A2B('10')
Character-valued built-in functions

Character-valued built-in functions have arithmetic-only operands, character-only operands, or both arithmetic and character operands. Each type is described in a separate section. The maximum string length of any SETC variable is 1024 bytes. If this length is exceeded, the string value is truncated, and message ASMA091E is generated.

The following discussion uses these special notations:

n
The EBCDIC character containing all 0 bits.
f
The EBCDIC character containing all 1 bits.

Here are the SETC built-in functions:

A2B
Format: Function-invocation
Operands: Arithmetic
Output: A2B(aexpr) converts the value of its arithmetic argument to a string of 32 zero ('0') and one ('1') characters. The value of aexpr must be representable as a 32-bit binary integer. If the aexpr argument is negative, the result contains 32 characters, the first of which is '1'.

Examples

A2B(0)            has value '00000000000000000000000000000000'
A2B(5)            has value '00000000000000000000000000000101'
A2B(1022)         has value '00000000000000000000001111111110'
A2B(-7)           has value '11111111111111111111111111111001'
A2B(2345678901)   indicates an error (value too large)
A2C
Format: Function-invocation
Operands: Arithmetic
Output: A2C(aexpr) converts the value of its arithmetic argument to a string of four characters whose bit pattern is the same as the argument's.

Examples

A2C(0)            has value 'nnnn' (4 EBCDIC nulls)
A2C(241)          has value 'nnn1'
A2C(20046)        has value 'nn++'
A2C(-252645136)   has value '0000'
A2D
Format: Function-invocation
Operands: Arithmetic
Output: A2D(aexpr) converts the value of its arithmetic argument to a string of decimal digits preceded by a plus or minus sign.

Note: The A2D function is similar to the SIGNED function, except that A2D always provides an initial sign character.

Examples

A2D(0)            has value '+0'
A2D(241)          has value '+241'
A2D(16448)        has value '+16448'
A2D(-3)           has value '-3'
A2X
Format: Function-invocation
Operands: Arithmetic
Output: A2X(aexpr) converts the value of its arithmetic argument to a string of eight hexadecimal characters.

Examples

A2X(0)            has value '00000000'
A2X(10)           has value '0000000A'
A2X(257)          has value '00000101'
A2X(1022)         has value '000003FE'
A2X(-7)           has value 'FFFFFFF9'
B2C
Format: Function-invocation
Operands: Character
Output: B2C('bitstring') converts the bit-string character argument to characters representing the same bit pattern. Null arguments return a null string.

If needed, the argument string is padded internally on the left with zeros so that its length is a multiple of eight.

The operand must contain only ones and zeros. Any other value causes the message ASMA214E to be generated.

Examples

B2C('11110011')        has value '3'
B2C('101110011110001') has value '*1'
B2C('0')               has value 'n' (EBCDIC null character)
B2C('00010010001')     has value 'nj'
B2C('000000000')       has value 'nn' (two EBCDIC nulls)
B2C('')                has value ''  (null string)
B2D
Format: Function-invocation
Operands: Character
Output: B2D('bitstring') converts a bit-string argument of at most 32 '0' and '1' characters to one to ten decimal characters preceded by a plus or minus sign, representing the value of the argument. Null arguments return '+0'.

Examples

B2D('')                has value '+0'
B2D('00010010001')     has value '+145'
B2D('11110001')        has value '+241'
B2D('01111111111111111111111111111111') has value '+2147483647'
B2D('11111111111111111111111111110001') has value '-15'
B2X
Format: Function-invocation
Operands: Character
Output: B2X('bitstring') converts the bit-string argument to hexadecimal characters representing the same bit pattern. Null arguments return a null string.

If needed, the argument string is padded internally on the left with zeros so that its length is a multiple of four.

The operand must contain only ones and zeros. Any other value causes the message ASMA214E to be generated.

Examples

B2X('')                  has value ''  (null string)
B2X('00000')             has value '00'
B2X('0000010010001')     has value '0091'
B2X('11110001')          has value 'F1'
B2X('1111110001')        has value '3F1'
BYTE
Format: Logical-expression, function-invocation
Operands: Arithmetic
Output: BYTE(aexpr) or (BYTE aexpr) returns a one-character EBCDIC character expression in which the binary value of the character is specified by the arithmetic argument. The argument must have a value between 0 and 255, inclusive.

This function might be used to introduce characters which are not on the keyboard.

Examples

BYTE(0)           has value 'n' (EBCDIC null character)
BYTE(97)          has value '/'
BYTE(129)         has value 'a'
C2B
Format: Function-invocation
Operands: Character
Output: C2B('charstring') converts the character argument to a string of '0' and '1' characters representing the same bit pattern. Null arguments return a null string.

If the result is not too long, the length of the result is eight times the length of the 'charstring' argument.

Examples

C2B('')           has value ''
C2B('n')          has value '00000000'
C2B(' ')          has value '01000000'
C2B('1')          has value '11110001'
C2B('1234')       has value '11110001111100101111001111110100'
C2D
Format: Function-invocation
Operands: Character
Output: C2D('charstring') converts a character-string argument of at most four characters to one to ten decimal characters preceded by a plus or minus sign, representing the numeric value of the argument. Null arguments return '+0'.

Examples

C2D('')            has value '+0'
C2D('nj')          has value '+145'
C2D('1')           has value '+241'
C2D('0000')        has value '-252645136
C2X
Format: Function-invocation
Operands: Character
Output: C2X('charstring') converts the character-string argument to hexadecimal characters representing the same bit pattern. Null arguments return a null string.

If the result is not too long, the length of the result is two times the length of the 'charstring' argument.

Examples

C2X('')           has value ''
C2X('n')          has value '00'
C2X('1')          has value 'F1'
C2X('a')          has value '81'
C2X('1234567R')   has value 'F1F2F3F4F5F6F7D9'
D2B
Format: Function-invocation
Operands: Character
Output: D2B('decstring') converts an argument string of optionally signed decimal characters to a string of 32 '0' and '1' characters representing a bit string with the same binary value. The value of decstring must be representable as a 32-bit binary integer. A null argument string returns a null string.

Examples

D2B('')           has value ''
D2B('0')          has value '00000000000000000000000000000000'
D2B('+5')         has value '00000000000000000000000000000101'
D2B('1022')       has value '00000000000000000000001111111110'
D2B('-7')         has value '11111111111111111111111111111001'
D2C
Format: Function-invocation
Operands: Character
Output: D2C('decstring') converts an argument string of optionally signed decimal characters to a string of four characters whose byte values represent the same binary value. The value of decstring must be representable as a 32-bit binary integer. The argument string may not be null.

Examples

D2C('')           indicates an error
D2C('0')          has value 'nnnn' (4 EBCDIC null bytes)
D2C('126')        has value 'nnn='
D2C('247')        has value 'nnn7'
D2C('23793')      has value 'nn*1'
D2C('-7')         has value 'fff9' (f=byte of all 1-bits)
D2X
Format: Function-invocation
Operands: Character
Output: D2X('decstring') converts an argument string of optionally signed decimal characters to a string of eight hexadecimal characters whose digits represent the same hexadecimal value. The value of decstring must be representable as a 32-bit binary integer. The argument string may not be null.

Examples

D2X('')           indicates an error
D2X('0')          has value '00000000'
D2X('+5')         has value '00000005'
D2X('255')        has value '000000FF'
D2X('01022')      has value '000003FE'
D2X('-7')         has value 'FFFFFFF9'
DSX('2345678901') causes an error condition (value too large)
DCVAL
Format: Function-invocation
Operands: Character
Output: DCVAL('cexpr') performs a single scan of the argument string to find successive pairs of apostrophes and ampersands, and returns a string value in which each such pair has been replaced by a single occurrence. This pairing action occurs only once; that is, three successive occurrences of an apostrophe or ampersand will result in two occurrences, not one. A null argument is returned unchanged.

DCVAL is similar to DCLEN, except that DCLEN returns only the length of the result, not the paired string.

Examples

DCVAL('')         has value "" (null string)
DCVAL('''')       has value "'" (single apostrophe)
DCVAL('&&')       has value "&" (single ampersand)
DCVAL('a''''b')   has value "a'b"
DCVAL('a''''b&&c')   has value "a'b&c"
.* Suppose &C has value "&&&'''"  (3 ampersands, 3 apostrophes)
&X  SETC  DCVAL('&C')  &X has value "&&''" (2 of each)
DEQUOTE
Format: Function-invocation
Operands: Character
Output: DEQUOTE('cexpr') removes a single occurrence of an apostrophe from each end of the argument string, if any are present. A null argument is returned unchanged.

Examples

&C   SETC  DEQUOTE('charstring')    &C has value "charstring"
&C   SETC  DEQUOTE('')              &C is a null string
&C   SETC  DEQUOTE('a')             &C has value "a"
&ARG SETC  '''a'''                  &ARG has value "'a'"
&C   SETC  DEQUOTE('&ARG')          &C has value "a"
&C   SETC  DEQUOTE('a''b')          &C has value "a'b"
&ARG SETC  ''''''                   &ARG has value "''"
&C   SETC  DEQUOTE('&ARG')          &C has value "" (null string)
DOUBLE
Format: Logical-expression, function-invocation
Operands: Character
Output: DOUBLE('cexpr') or (DOUBLE 'cexpr') converts each occurrence of an apostrophe or ampersand character in the argument string to a pair of apostrophes and ampersands. In this form, the string is suitable for substitution into statements such as DC and MNOTE. Null arguments return a null string. An error condition is detected if the resulting string is too long.

Examples

Suppose the SETC variable &C contains the characters "&&''&" (two apostrophes, three ampersands):

DOUBLE('&C')           has value "&&&&''''&&"
LOWER
Format: Logical-expression, function-invocation
Operands: Character
Output: LOWER('cexpr') or (LOWER 'cexpr') converts the alphabetic characters A-Z in the argument to lower case, a-z. Null arguments return a null string.

Examples

LOWER('aBcDefG')       has value 'abcdefg'
SIGNED
Format: Logical-expression, function-invocation
Operands: Arithmetic
Output: SIGNED(aexpr) or (SIGNED aexpr) converts its arithmetic argument to a decimal character string representation of its value, with a leading minus sign if the argument is negative.

Examples

SIGNED(10)        has value '10'
SIGNED(-10)       has value '-10'

Note: The SIGNED function creates properly signed values for display, whereas assigning a SETA value to a SETC variable produces only the magnitude of the SETA value. For example:

&A   SETA  10     &A has value 10
&C   SETC  '&A'   &C has value '10'
&A   SETA  -10    &A has value -10
&C   SETC  '&A'   &C has value '10' (unsigned)
SYSATTRA
Format: Function-invocation
Operands: Character
Output: SYSATTRA('symbol') returns the assembler-type value for the specified symbol.

Examples

Given that symbol Sym1 has previously been assigned an assembler type of GR, and variable symbol &SName has a value of SYM1, then:

SYSATTRA('Sym1')       has value 'GR'
SYSATTRA('&Sname')     has value 'GR'
SYSATTRP
Format: Function-invocation
Operands: Character
Output: SYSATTRP('symbol') returns the program-type value for the specified symbol.

Examples

Given that symbol Sym1 has previously been assigned a program type of "Box7", and variable symbol &SName has a value of SYM1, then:

SYSATTRP('Sym1')       has value 'Box7'
SYSATTRP('&SName')     has value 'Box7'
UPPER
Format: Logical-expression, function-invocation
Operands: Character
Output: UPPER('cexpr') or (UPPER 'cexpr') converts the alphabetic characters a-z in the argument to upper case, A-Z. Null arguments return a null string.

Examples

UPPER('aBcDefG')       has value 'ABCDEFG'
X2B
Format: Function-invocation
Operands: Character
Output: X2B('hexstring') converts the value of its argument string of hexadecimal characters to a character string containing only zero ('0') and one ('1') characters representing the same bit pattern. Null arguments return a null string.

If the result is not too long, the length of the result is four times the length of the 'hexstring' argument.

The operand must contain only hexadecimal digits. Any other value causes the message ASMA214E to be generated.

Examples

X2B('')           has value '' (null string)
X2B('00')         has value '00000000'
X2B('1')          has value '0001'
X2B('F3')         has value '11110011'
X2B('00F3')       has value '0000000011110011'
X2C
Format: Function-invocation
Operands: Character
Output: X2C('hexstring') converts the hexstring argument to characters representing the same bit pattern. Null arguments return a null string.

If needed, the argument string is padded internally on the left with a zero character so that its length is a multiple of two.

The operand must contain only hexadecimal digits. Any other value causes the message ASMA214E to be generated.

Examples

X2C('')           has value '' (null string)
X2C('F3')         has value '3'
X2C('0')          has value 'n' (EBCDIC null character)
X2C('F1F2F3F4F5') has value '12345'
X2C('000F1')      has value 'nn1'
X2D
Format: Function-invocation
Operands: Character
Output: X2D('hexstring') converts its argument string of at most eight hexadecimal characters to one to ten decimal characters preceded by a plus or minus sign, representing the value of the argument. Null arguments return '+0'. For example:
X2D('')            has value '+0'
X2D('91')          has value '+145'
X2D('000F1')       has value '+241'
X2D('7FFFFFFF')    has value '+2147483647'
X2D('FFFFFFF1')    has value '-15'

Figure 45. Defining character (SETC) expressions
*-----------*
|           |
|Character  |
|Expression |
|           |
*-----*-----*
      |
      V Can be any of
      *-------------*-------------*----------------------*
      V             V             V                      V
*-----*-----* *-----*------* *----*--------------* *-----*--------*------------*
|           | |            | |                   | |              |            |
| Character | | CharExpr   | | Character-Valued  | | (Duplication | CharExpr   |
| Value     | |     . <--* | | Built-In Function | | Factor)      |            |
|           | | CharExpr | | |                   | |              |            |
*-----*-----* *----------+-* *-------------------* *--------------*------------*
      |                  |
      |                  *-- Period (.) = Concatenation Character
      V Can be any of
      *-------------*-------------*-------------*
      V             V             V             V
*-----*-----* *-----*-----* *-----*-----* *-----*-----*
| Substring | | Variable  | | Self-     | | Attribute1|
|           | | Symbol    | | Defining  | | Reference |
|           | |           | | Term      | |           |
|           | |           | |           | | T' or O'  |
*-----------* *-----------* *-----------* *-----------*

Notes:
  1. The attribute reference term must not be preceded by a duplication factor.
Evaluation of character expressions

The value of a character expression is the character string within the enclosing single quotation marks, after the assembler carries out any substitution for variable symbols.

Character strings, including variable symbols, can be concatenated to each other within a character expression. The resultant string is the value of the expression.

Notes:
  1. Use two single quotation marks to generate a single quotation mark as part of the value of a character expression.

    The following statement assigns the character value L'SYMBOL to the SETC symbol &LENGTH.

    &LENGTH  SETC            'L''SYMBOL'
  2. A double ampersand generates a double ampersand as part of the value of a character expression. To generate a single ampersand in a character expression, use the substring notation; for example:
    &AMP     SETC            '&&'(1,1)
    Note:
    A quoted single ampersand '&' is not a valid character string.

    The following statement assigns the character value HALF&& to the SETC symbol &AND.

    &AND     SETC            'HALF&&'

    This is the only instance when the assembler does not pair ampersands to produce a single ampersand. However, if you substitute a SETC symbol with such a value into the nominal value in a DC instruction operand, or the operand of an MNOTE instruction, when the assembler processes the DC or MNOTE instruction, it pairs the ampersands and produces a single ampersand.

  3. To generate a period, two periods must be specified after a variable symbol.

    For example, if &ALPHA has been assigned the character value AB%4, the following statement can be used to assign the character value AB%4.RST to the variable symbol &GAMMA.

    &GAMMA   SETC            '&ALPHA..RST'
  4. To generate a period, the variable symbol may have a period as part of its value. For example:
    &DOT    SETC  '.'
    &DELTA  SETC  'A&DOT.&DOT'    &DELTA has value 'A..'
  5. Double-byte data can appear in the character string if the assembler is invoked with the DBCS option. The double-byte data must be bracketed by the SO and SI delimiters, and the double-byte data must be valid.
  6. The DBCS ampersand and apostrophe are not recognized as delimiters.
  7. A double-byte character that contains the value of an EBCDIC ampersand or apostrophe in either byte is not recognized as a delimiter when enclosed by SO and SI.
  8. Duplication (replication) factors are permitted before character built-in functions.
  9. Releases of HLASM prior to Version 1 Release 4 permitted predefined absolute symbols in character expressions. To remove inconsistencies when handling character and arithmetic expressions such usage is no longer permitted and results in message ASMA137S if attempted. The built-in function BYTE can be used to convert a numeric value in a character expression as shown.
      RPTDS      EQU     X'01'
      &RPTC1     SETC    'SEND  '.(BYTE RPTDS)
Concatenation of character string values

Character expressions can be concatenated to each other or to substring notations in any order. The resulting value is a character string composed of the concatenated parts. This concatenated string can then be used in the operand field of a SETC instruction, or as a value for comparison in a logical expression.

You need the concatenation character (a period) to separate the single quotation mark that ends one character expression from the single quotation mark that begins the next.

For example, either of the following statements may be used to assign the character value ABCDEF to the SETC symbol &BETA.

&BETA    SETC            'ABCDEF'
&BETA    SETC            'ABC'.'DEF'
Concatenation of strings containing double-byte data

If the assembler is invoked with the DBCS option, then the following additional considerations apply:

Examples:

&DBDA    SETC            '<Da>'
&SO      SETC            BYTE(X'0E')
&SI      SETC            BYTE(X'0F')
&DBCS1A  SETC            '&DBDA.<Db>'
&DBCS1E  SETC            '&DBDA<Db>'
&DBCS2   SETC            '&DBDA'.'<Db>'
&DBCS2A  SETC            '&DBDA'.'<Db>'.'&DBDA'
&DBCS3   SETC            '&DBDA'.'&SI'.'&SO'.'<Db>'
&DBCS3P  SETC            '&DBDA'.'&SI'
&DBCS3Q  SETC            '&SO'.'<Db>'
&DBCS3R  SETC            '&DBCS3P'.'&DBCS3Q'

These examples use the BYTE function to create variables &SO and &SI, which have the values of SO and SI, respectively. The variable &DBCS1A is assigned the value <DaDb> with the SI/SO pair at the join removed. The assignment to variable &DBCS1E fails with error ASMA035E Invalid delimiter, because the symbol &DBDA is terminated by SO and not by a period. The variable &DBCS2 is assigned the value <DaDb>. The variable &DBCS2A is assigned the value <DaDbDa>. As with &DBCS1A, redundant SI/SO pairs are removed at the joins. The variable &DBCS3 is assigned the value <DaDb>. Although SI and SO have been added at the join, the concatenation operation removes two SI and two SO characters, since redundant SI/SO pairs are found at the second and third concatenations. However, by using intermediate variables &DBCS3P and &DBCS3Q to change the order of concatenation, the string <Da><Db> can be assigned to variable &DBCS3R. Note that substituting the variable symbol &DBCS3R in the nominal value of a G-type constant results in removal of the SI/SO pair at the join.

Using SETC symbols

The character value assigned to a SETC symbol is substituted for the SETC symbol when it is used in the name, operation, or operand field of a statement.

For example, consider the following macro definition, macro instruction, and generated statements:

          MACRO
 &NAME    MOVE            &TO,&FROM
          LCLC            &PREFIX
 &PREFIX  SETC            'FIELD'             Statement 1
 &NAME    ST              2,SAVEAREA
          L               2,&PREFIX&FROM      Statement 2
          ST              2,&PREFIX&TO        Statement 3
          L               2,SAVEAREA
          MEND
 -------------------------------------------------------------------
 HERE     MOVE            A,B
 -------------------------------------------------------------------
+HERE ST             2,SAVEAREA
+     L              2,FIELDB
+     ST             2,FIELDA
+     L              2,SAVEAREA

Statement 1 assigns the character value FIELD to the SETC symbol &PREFIX. In statements 2 and 3, &PREFIX is replaced by FIELD.

The following example shows how the value assigned to a SETC symbol may be changed in a macro definition.

          MACRO
 &NAME    MOVE            &TO,&FROM
          LCLC            &PREFIX
 &PREFIX  SETC            'FIELD'             Statement 1
 &NAME    ST              2,SAVEAREA
          L               2,&PREFIX&FROM      Statement 2
 &PREFIX  SETC            'AREA'              Statement 3
          ST              2,&PREFIX&TO        Statement 4
          L               2,SAVEAREA
          MEND
 -------------------------------------------------------------------
 HERE     MOVE            A,B
 -------------------------------------------------------------------
+HERE ST             2,SAVEAREA
+     L              2,FIELDB
+     ST             2,AREAA
+     L              2,SAVEAREA

Statement 1 assigns the character value FIELD to the SETC symbol &PREFIX. Therefore, &PREFIX is replaced by FIELD in statement 2. Statement 3 assigns the character value AREA to &PREFIX. Therefore, &PREFIX is replaced by AREA, instead of FIELD, in statement 4.

The following example uses the substring notation in the operand field of a SETC instruction.

          MACRO
 &NAME    MOVE            &TO,&FROM
          LCLC            &PREFIX
 &PREFIX  SETC            '&TO'(1,5)          Statement 1
 &NAME    ST              2,SAVEAREA
          L               2,&PREFIX&FROM      Statement 2
          ST              2,&TO
          L               2,SAVEAREA
          MEND
 -------------------------------------------------------------------
 HERE     MOVE            FIELDA,B
 -------------------------------------------------------------------
+HERE ST             2,SAVEAREA
+     L              2,FIELDB
+     ST             2,FIELDA
+     L              2,SAVEAREA

Statement 1 assigns the substring character value FIELD (the first five characters corresponding to symbolic parameter &TO to the SETC symbol &PREFIX. Therefore, FIELD replaces &PREFIX in statement 2.

Notes:
  1. If the COMPAT(SYSLIST) assembler option is not specified, you can pass a sublist into a macro definition by assigning the sublist to a SETC symbol, and then specifying the SETC symbol as an operand in a macro instruction. However, if the COMPAT(SYSLIST) assembler option is specified, sublists assigned to SETC symbols are treated as a character string, not as a sublist.
  2. Regardless of the setting of the COMPAT(SYSLIST) assembler option, you can not pass separate (as opposed to a sublist of) parameters into a macro definition, by specifying a string of values separated by commas as the operand of a SETC instruction and then using the SETC symbol as an operand in the macro instruction. If you attempt to do this, the operand of the SETC instruction is passed to the macro instruction as one parameter, not as a list of parameters.
Concatenating substring notations and character expressions

Substring notations (see Substring notation) can be concatenated with character expressions in the operand field of a SETC instruction. If a substring notation follows a character expression, the two can be concatenated by placing a period between the terminating single quotation mark of the character expression and the opening single quotation mark of the substring notation.

For example, if &ALPHA has been assigned the character value AB%4, and &BETA has been assigned the character value ABCDEF, the following statement assigns &GAMMA the character value AB%4BCD:

&GAMMA   SETC            '&ALPHA'.'&BETA'(2,3)

If a substring notation precedes a character expression or another substring notation, the two can be concatenated by writing the opening single quotation mark of the second item immediately after the closing parenthesis of the substring notation.

Optionally, you can place a period between the closing parenthesis of a substring notation and the opening single quotation mark of the next item in the operand field.

If &ALPHA has been assigned the character value AB%4, and &ABC has been assigned the character value 5RS, either of the following statements can be used to assign &WORD the character value AB%45RS.

&WORD    SETC            '&ALPHA'(1,4).'&ABC'
&WORD    SETC            '&ALPHA'(1,4)'&ABC'(1,3)

If a SETC symbol is used in the operand field of a SETA instruction, the character value assigned to the SETC symbol must be 1-to-10 decimal digits (not greater than 2147483647), or a valid self-defining term.

If a SETA symbol is used in the operand field of a SETC statement, the magnitude of the arithmetic value is converted to an unsigned integer with leading zeros removed. If the value is 0, it is converted to a single 0.


[ Top of Page | Previous Page | Next Page | Contents | Index ]