High Level Assembler for z/OS & z/VM & z/VSE. Language Reference (Version 1 Release 6) - page 21
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 52).
Sample Program - LRSAMP03 - HLASM
Page
3
Active Usings: None
Loc
Object Code
Addr1
Addr2
Stmt Source Statement
HLASM R6.0
2015/02/23 09.49
2 ***********************************************************************
3 *
4 * Licensed Materials - Property of IBM
5 *
6 *
5696-234
7 *
8 * Copyright IBM Corporation 2008, 2015 All Rights Reserved.
9 *
10 * US Government Users Restricted Rights - Use, duplication
11 * or disclosure restricted by GSA ADP Schedule Contract
12 * with IBM Corp.
13 *
14 ***********************************************************************
00000000
00000000 00000000
15 LPSAMP03 CSECT
16
ACONTROL FLAG(NOSUBSTR)
17 &STRING
SETC
’STRING’
18 &SUBSTR1 SETC
’&STRING’(0,4)
** ASMA093E Substring expression 1 less than 1; default=null - OPENC
** ASMA435I Record 18 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP03) on volume: 37P003
19 &SUBSTR2 SETC
’&STRING’(7,4)
** ASMA092E Substring expression 1 points past string end; default=null - OPENC
** ASMA435I Record 19 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP03) on volume: 37P003
20 &SUBSTR3 SETC
’&STRING’(3,0)
21 &SUBSTR4 SETC
’&STRING’(3,-2)
** ASMA095W Substring expression 2 less than 0; default=null - OPENC
** ASMA435I Record 21 in SMORSA.BOOK.SAMPLE.ASM(LRSAMP03) on volume: 37P003
22 &SUBSTR5 SETC
’&STRING’(3,4)
23 &SUBSTR6 SETC
’&STRING’(3,5)
24
END
Figure 52. Sample assembly using substring notation with messages suppressed
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
AIF
(’&C’ EQ ’STRING1’).B
character relation
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 4064 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:
Chapter 9. How to write conditional assembly instructions
381
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 like 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
382
HLASM V1R6 Language Reference
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.
Chapter 9. How to write conditional assembly instructions
383
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 0 - 255.
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
384
HLASM V1R6 Language Reference
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 must 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
Chapter 9. How to write conditional assembly instructions
385
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 must 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 result in two occurrences, not one. A null
argument is returned unchanged.
DCVAL is like 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 "&&&&'’''" (4 ampersands, 4 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
386
HLASM V1R6 Language Reference
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 "&&&&’’’’&&"
|
ESYM
|
Format: Function-invocation
|
Operands: Character
|
Output: ESYM(’cexpr’) returns the external symbol. This built-in function
|
is valid on z/OS 2.1 and higher systems. You can define a JCL symbol
|
name the same as a system symbol name. When a JCL symbol has the
|
same name as a system symbol, the substitution text for the JCL symbol
|
overrides the substitution text for the system symbol.
|
Examples
|
&C SETC ESYM(’SYSNAME’) &C has value for the external symbol &SYSNAME
LOWER
Format: Logical-expression, function-invocation
Operands: Character
Output: LOWER(’cexpr’) or (LOWER ’cexpr’) converts the alphabetic
characters A-Z in the argument to lowercase, 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:
Chapter 9. How to write conditional assembly instructions
387
&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.
v The 1 to 4 character assembler type is returned, with trailing spaces
removed. For symbols defined in DC and DS statements, the assembler
type includes the type extensions, if any.
v Symbols without an assigned assembler type, undefined symbols, and
null arguments return null.
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.
v The 4 byte program type is returned.
v Symbols without an assigned program type, undefined symbols, and
null arguments return null.
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 uppercase, A-Z. Null arguments return a
null string.
Examples
UPPER(’aBcDefG’)
has value ’ABCDEFG’
X2B
Format: Function-invocation
Operands: Character
388
HLASM V1R6 Language Reference
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’
Evaluation of character expressions: The value of a character expression is the
character string within the enclosing apostrophes, 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.
Chapter 9. How to write conditional assembly instructions
389
Notes:
1.
Use two apostrophes to generate a single apostrophe 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:
&
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 must 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.
390
HLASM V1R6 Language Reference
You need the concatenation character (a period) to separate the apostrophe that
ends one character expression from the apostrophe that begins the next.
For example, either of the following statements can 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:
v When a variable symbol adjoins double-byte data, the SO delimiting the
double-byte data is not a valid delimiter of the variable symbol. The variable
symbol must be terminated by a period.
v The assembler checks for SI and SO at concatenation points. If the byte to the
left of the join is SI and the byte to the right of the join is SO, then the SI/SO
pair is considered redundant and are removed.
v To create redundant SI/SO pairs at concatenation points, use the substring
notation and SETC expressions to create additional SI and SO characters. By
controlling the order of concatenation, you can leave a redundant SI/SO pair at
a concatenation point.
Instead of substring notation, you can use the BYTE function to create additional
SI and SO characters:
&SO SETC (BYTE 14)
&SI SETC (BYTE 15)
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. 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. 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.
Chapter 9. How to write conditional assembly instructions
391
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 can 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
-------------------------------------------------------------------
392
HLASM V1R6 Language Reference
+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
cannot 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” on page 378) 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 apostrophe of the character expression and the
opening apostrophe 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 apostrophe 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 apostrophe 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.
Chapter 9. How to write conditional assembly instructions
393
Extended SET statements
As well as assigning single values to SET symbols, you can assign values to
multiple elements in an array of a subscripted SET symbol with one single SETx
instruction. Such an instruction is called an extended SET statement.
,
▼
►► variable_symbol(subscript)
SETA
operand
►◄
SETB
SETC
variable_symbol(subscript)
Is a variable symbol and a subscript that shows the position in the SET symbol
array to which the first operand is to be assigned.
operand
Is the arithmetic value, binary value, or character value to be assigned to the
corresponding SET symbol array element.
The first operand is assigned to the SET symbol denoted by
variable_symbol(subscript). Successive operands are then assigned to successive
positions in the SET symbol array. If an operand is omitted, the corresponding
element of the array is unchanged. Consider the following example:
LCLA
&LIST(50)
&LIST(3) SETA
5,10,,20,25,30
The first instruction declares &LIST as a subscripted local SETA symbol. The second
instruction assigns values to certain elements of the array &LIST. Thus, the
instruction does the same as the following sequence:
&LIST(3) SETA
5
&LIST(4) SETA
10
&LIST(6) SETA
20
&LIST(7) SETA
25
&LIST(8) SETA
30
Alternative statement format
You can use the alternative statement format for extended SETx statements. This
coding can be written as:
&LIST(3) SETA
5,
THIS IS
X
10,,
AN ARRAY
X
20,25,30
SPECIFICATION
SETAF instruction
Use the SETAF instruction to call an external function to assign any number of
arithmetic values to a SETA symbol. You can assign many parameters—the exact
number depending on factors such as the size of the program and of virtual
storage—to pass to the external function routine.
The SETAF instruction can be used anywhere that a SETA instruction can be used.
394
HLASM V1R6 Language Reference
►► variable_symbol SETAF 'function─name'
►◄
▼
,expression
variable symbol
Is a variable symbol.
A global variable symbol in the name field must have been previously declared
as a SETA symbol in a GBLA instruction. Local SETA symbols need not be
declared in an LCLA instruction. The assembler considers any undeclared
variable symbol found in the name field of a SETA instruction as a local SET
symbol.
The variable symbol is assigned a type attribute value of N.
function_name
The name of an external function load module. The name must be specified as
a character expression, and must evaluate to a valid module name no longer
than eight bytes.
See the chapter “Providing External Functions” in the HLASM Programmer's
Guide for information about external function load modules.
expression
Is an arithmetic expression evaluated as a signed 32 bit arithmetic value. The
minimum and maximum allowable values of the expression are -231 and +231-1.
See “SETA instruction” on page 355 for further information about setting SETA
symbols, and ways to specify arithmetic expressions.
The function name must be enclosed in single quotes. For example:
&MAX_VAL SETAF
’MAX’,7,4
Calls the external function X
MAX, passing values 7 and
X
4 as operands.
SETCF instruction
Use the SETCF instruction to call an external function to assign a character value
to a SETC symbol. You can specify a many parameters—the exact number
depending on factors such as the size of the program and of virtual storage—to
pass to the external function routine.
The SETCF instruction can be used anywhere that a SETC instruction can be used.
►► variable_symbol SETCF 'function─name'
►◄
▼
,character_value
variable symbol
Is a variable symbol.
Chapter 9. How to write conditional assembly instructions
395
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 an 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.
The character value assigned to the variable symbol can have a string length in
the range 0 (for a null character string) through 1024.
function_name
The name of an external function load module. The name must be specified as
a character expression, and must evaluate to a valid module name no longer
than eight bytes.
See the chapter “Providing External Functions” in the HLASM Programmer's
Guide for information about external function load modules.
character_value
Is a character value specified by:
v A type attribute reference
v An operation code attribute reference
v A character expression
v A substring notation
v A concatenation of one or more of the above
The character value can have a string length in the range 0 (for a null character
string) through 1024.
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.
See “SETC instruction” on page 375 for further information about setting SETC
symbols, and ways to specify character expressions.
Branching
You can control the sequence in which source program statements are processed by
the assembler by using the conditional assembly branch instructions described in
this section.
AIF instruction
Use the AIF instruction to branch according to the results of a condition test. You
can thus alter the sequence in which source program statements or macro
definition statements are processed by the assembler.
The AIF instruction also provides loop control for conditional assembly processing,
which lets you control the sequence of statements to be generated.
It also lets you check for error conditions and thus branch to the appropriate
MNOTE instruction to issue an error message.
►►
AIF
(logical_expression)sequence_symbol
►◄
sequence_symbol
396
HLASM V1R6 Language Reference
sequence_symbol
Is a sequence symbol
logical_expression
Is a logical expression (see “Logical (SETB) expressions” on page 372) the
assembler evaluates during conditional assembly time to determine if it is true
or false. If the expression is true (logical value=1), the statement named by the
sequence symbol in the operand field is the next statement processed by the
assembler. If the expression is false (logical value=0), the next sequential
statement is processed by the assembler.
In the following example, the assembler branches to the label .OUT if &C = YES:
AIF
(’&C’ EQ ’YES’).OUT
.ERROR ANOP
.OUT
ANOP
The sequence symbol in the operand field is a conditional assembly label that
represents a statement number during conditional assembly processing. It is the
number of the statement that is branched to if the logical expression preceding the
sequence symbol is true.
The statement identified by the sequence symbol referred to in the AIF instruction
can appear before or after the AIF instruction. However, the statement must appear
within the local scope of the sequence symbol. Thus, the statement identified by
the sequence symbol must appear:
v In open code, if the corresponding AIF instruction appears in open code
v In the same macro definition in which the corresponding AIF instruction
appears.
You cannot branch from open code into a macro definition or between macro
definitions, regardless of nested calls to other macro definitions.
The following macro definition generates the statements needed to move a
fullword fixed-point number from one storage area to another. The statements are
generated only if the type attribute of both storage areas is the letter F.
MACRO
&N
MOVE
&T,&F
AIF
(T’&T NE T’&F).END Statement 1
AIF
(T’&T NE ’F’).END Statement 2
&N
ST
2,SAVEAREA
Statement 3
L
2,&F
ST
2,&T
L
2,SAVEAREA
.END
MEND
Statement 4
The logical expression in the operand field of Statement 1 has the value true if the
type attributes of the two macro instruction operands are not equal. If the type
attributes are equal, the expression has the logical value false.
Therefore, if the type attributes are not equal, Statement 4 (the statement named by
the sequence symbol .END) is the next statement processed by the assembler. If the
type attributes are equal, Statement 2 (the next sequential statement) is processed.
Chapter 9. How to write conditional assembly instructions
397
The logical expression in the operand field of Statement 2 has the value true if the
type attribute of the first macro instruction operand is not the letter F. If the type
attribute is the letter F, the expression has the logical value false.
Therefore, if the type attribute is not the letter F, Statement 4 (the statement named
by the sequence symbol .END) is the next statement processed by the assembler. If
the type attribute is the letter F, Statement 3 (the next sequential statement) is
processed.
Extended AIF instruction
The extended AIF instruction combines several successive AIF statements into one
statement.
,
►►
AIF
▼
(logical_expression)sequence_symbol
►◄
sequence_symbol
sequence_symbol
Is a sequence symbol
logical_expression
Is a logical expression the assembler evaluates during conditional assembly
time to determine if it is true or false. If the expression is true (logical value=1),
the statement named by the sequence symbol in the operand field is the next
statement processed by the assembler. If the expression is false (logical
value=0), the next logical expression is evaluated.
The extended AIF instruction is exactly equivalent to n successive AIF statements.
The branch is taken to the first sequence symbol (scanning left to right) whose
corresponding logical expression is true. If none of the logical expressions is true,
no branch is taken.
Example:
Cont.
AIF
(’&L’(&C,1) EQ ’$’).DOLR,
X
(’&L’(&C,1) EQ ’#’).POUND,
X
(’&L’(&C,1) EQ ’@’).AT,
X
(’&L’(&C,1) EQ ’=’).EQUAL,
X
(’&L’(&C,1) EQ ’(’).LEFTPAR,
X
(’&L’(&C,1) EQ ’+’).PLUS,
X
(’&L’(&C,1) EQ ’-’).MINUS
This statement looks for the occurrence of a $, #, @, =, (, +, and -, in that order; and
causes control to branch to .DOLR, .POUND, .AT, .EQUAL, .LEFTPAR, .PLUS, and
.MINUS, if the string being examined contains any of these characters at the
position designated by &C.
Alternative format for AIF instruction
The alternative statement format is allowed for extended AIF instructions. This
format is illustrated in the above example.
398
HLASM V1R6 Language Reference
AIFB—synonym of the AIF instruction
For compatibility with some earlier assemblers, High Level Assembler supports the
AIFB symbolic operation code as a synonym of the AIF instruction. However, do
not use the AIFB instruction in new applications as support for it might be
removed in the future.
AGO instruction
The AGO instruction branches unconditionally. You can thus alter the sequence in
which your assembler language statements are processed. This provides you with
final exits from conditional assembly loops.
►►
AGO sequence_symbol
►◄
sequence_symbol
sequence_symbol
Is a sequence symbol.
The statement named by the sequence symbol in the operand field is the next
statement processed by the assembler.
The statement identified by a sequence symbol referred to in the AGO instruction
can appear before or after the AGO instruction. However, the statement must
appear within the local scope of the sequence symbol. Thus, the statement
identified by the sequence symbol must appear:
v In open code, if the corresponding AGO instruction appears in open code
v In the same macro definition in which the corresponding AGO instruction
appears.
Example:
MACRO
&NAME
MOVE
&T,&F
AIF
(T’&T EQ ’F’).FIRST
Statement 1
AGO
.END
Statement 2
.FIRST AIF
(T’&T NE T’&F).END
Statement 3
&NAME
ST
2,SAVEAREA
L
2,&F
ST
2,&T
L
2,SAVEAREA
.END
MEND
Statement 4
Statement 1 determines if the type attribute of the first macro instruction operand
is the letter F. If the type attribute is the letter F, Statement 3 is the next statement
processed by the assembler. If the type attribute is not the letter F, Statement 2 is
the next statement processed by the assembler.
Statement 2 indicates to the assembler that the next statement to be processed is
Statement 4 (the statement named by sequence symbol .END).
Computed AGO instruction
The computed AGO instruction makes branches according to the value of an
arithmetic expression specified in the operand.
Chapter 9. How to write conditional assembly instructions
399
,
▼
►►
AGO
(arithmetic_expression)
sequence_symbol
►◄
sequence_symbol
sequence_symbol
Is a sequence symbol.
arithmetic_expression
Is an arithmetic expression the assembler evaluates to k, where k is 1 - n (the
number of occurrences of sequence_symbol in the operand field). The assembler
branches to the k-th sequence symbol in the list. If k is outside that range, no
branch is taken.
In the following example, control passes to the statement at .THIRD if &I= 3.
Control passes through to the statement following the AGO if &I is less than 1 or
greater than 4.
Cont.
AGO
(&I).FIRST,.SECOND,
X
.THIRD,.FOURTH
Alternative format for AGO instruction
The alternative statement format is allowed for computed AGO instructions. The
example can be coded:
Cont.
AGO
(&I).FIRST,
X
.SECOND,
X
.THIRD,
X
.FOURTH
AGOB - synonym of the AGO instruction
For compatibility with some earlier assemblers, High Level Assembler supports the
AGOB symbolic operation code as a synonym of the AGO instruction. However,
do not use the AGOB instruction in new applications as support for it might be
removed in the future.
ACTR instruction
The ACTR instruction sets a conditional assembly branch counter either within a
macro definition or in open code. The ACTR instruction can appear anywhere in
open code or within a macro definition.
Each time the assembler processes a successful AIF or AGO branching instruction
in a macro definition or in open code, the branch counter for that part of the
program is decremented by one. When the number of conditional assembly
branches reaches the value assigned to the branch counter by the ACTR
instruction, the assembler exits from the macro definition or stops processing
statements in open code.
By using the ACTR instruction, you avoid excessive looping during conditional
assembly processing.
400
HLASM V1R6 Language Reference