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.
|
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.
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.
&C2 SETC 'ABC'.(3)'ABCDEF'(4,3)assigns the value 'ABCDEFDEFDEF' to &C2.
&C3 SETC (3)'<.A.B>'assigns the value '<.A.B><.A.B><.A.B>' to &C3.
&C4 SETC (3)'<.A.B>'(2,4)assigns the value '.A.B.A.B.A.B' to &C4.
A EQU 123 &A1 SETA A &C5 SETC (3)'&A1'assigns the value '123123123' to &C5.
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.
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 20The 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.
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.
|
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)
The following examples show how the assembler processes substrings depending on the value of the elements n, e1, and e2.
Value of Variable Character Value Notation Symbol of Substring 'ABCDE'(1,5) ABCDE 'ABCDE'(2,3) BCD 'ABCDE'(2,*) BCDE 'ABCDE'(4,*) DE '&C'(3,3) ABCDE CDE '&PARAM'(3,3) ((A+3)*10) A+3
Character Value Notation of Substring 'ABCDE'(0,5) null character string 'ABCDE'(0,*) null character string
Value of Variable Character Value Notation Symbol of Substring 'ABCDE'(7,3) null character string 'ABCDE'(6,*) null character string
Value of Variable Character Value Notation Symbol of Substring 'ABCDE'(4,0) null character string 'ABCDE'(3,-2) null character string
Value of Variable Character Value Notation Symbol of Substring 'ABCDE'(3,5) CDE
Figure 43 shows the results of an assembly of SETC instructions with different substring notations.
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 00015000You 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).
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 00015000Character (SETC) expressions can be used only in conditional assembly instructions. Table 61 shows examples of using 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 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:
Here are the SETC built-in functions:
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)
Examples
A2C(0) has value 'nnnn' (4 EBCDIC nulls) A2C(241) has value 'nnn1' A2C(20046) has value 'nn++' A2C(-252645136) has value '0000'
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'
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'
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)
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'
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'
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'
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'
Examples
C2D('') has value '+0'
C2D('nj') has value '+145'
C2D('1') has value '+241'
C2D('0000') has value '-252645136
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'
Examples
D2B('') has value ''
D2B('0') has value '00000000000000000000000000000000'
D2B('+5') has value '00000000000000000000000000000101'
D2B('1022') has value '00000000000000000000001111111110'
D2B('-7') has value '11111111111111111111111111111001'
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)
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 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)
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)
Examples
Suppose the SETC variable &C contains the characters "&&''&" (two apostrophes, three ampersands):
DOUBLE('&C') has value "&&&&''''&&"
Examples
LOWER('aBcDefG') has value 'abcdefg'
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)
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'
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'
Examples
UPPER('aBcDefG') has value 'ABCDEFG'
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'
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('') has value '+0'
X2D('91') has value '+145'
X2D('000F1') has value '+241'
X2D('7FFFFFFF') has value '+2147483647'
X2D('FFFFFFF1') has value '-15'
*-----------*
| |
|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' |
*-----------* *-----------* *-----------* *-----------*
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.
The following statement assigns the character value L'SYMBOL to the SETC symbol &LENGTH.
&LENGTH SETC 'L''SYMBOL'
& SETC '&&'(1,1)
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.
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'
&DOT SETC '.' &DELTA SETC 'A&DOT.&DOT' &DELTA has value 'A..'
RPTDS EQU X'01' &RPTC1 SETC 'SEND '.(BYTE RPTDS)
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'
If the assembler is invoked with the DBCS option, then the following additional considerations apply:
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, 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.
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.
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 ]