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 is the EBCDIC character containing all 0 bits.
- f is the EBCDIC character containing all 1 bits.
- 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 ofaexpr
must be representable as a 32 bit binary integer. If theaexpr
argument is negative, the result contains 32 characters, the first of which is'1'
.ExamplesA2B(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.ExamplesA2C(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.
ExamplesA2D(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.ExamplesA2X(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.
ExamplesB2C('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'
.ExamplesB2D('') 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.
ExamplesB2X('') 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.
ExamplesBYTE(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.ExamplesC2B('') 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'
.ExamplesC2D('') 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.ExamplesC2X('') 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 ofdecstring
must be representable as a 32 bit binary integer. A null argument string returns a null string.ExamplesD2B('') 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 ofdecstring
must be representable as a 32 bit binary integer. A null argument string returns a null string.ExamplesD2C('') has value '' 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 ofdecstring
must be representable as a 32 bit binary integer. A null argument string returns a null string.ExamplesD2X('') has value '' 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.
ExamplesDCVAL('') 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 "&&&&''''&&"
- 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.ExamplesLOWER('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.ExamplesSIGNED(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 symbolSym1
has previously been assigned an assembler type ofGR
, and variable symbol &SName has a value ofSYM1
, 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 symbolSym1
has previously been assigned a program type ofBox7
, and variable symbol &SName has a value ofSYM1
, 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.ExamplesUPPER('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.
ExamplesX2B('') 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 thehexstring
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.
ExamplesX2C('') 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'