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 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

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 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

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

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

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 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:

&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.

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.
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.

The 4 byte program type is returned.
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

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'