Function Descriptions

The following are the DBCS functions and their descriptions.

DBADJUST

Read syntax diagramSkip visual syntax diagram>>-DBADJUST(string--+------------+--)--------------------------><
                    '-,operation-'
 

In EBCDIC, adjusts all contiguous SI and SO (or SO and SI) characters in string based on the operation specified. The following are valid operations. Only the capitalized and highlighted letter is needed; all characters following it are ignored.

Blank
changes contiguous characters to blanks (X'4040').
Remove
removes contiguous characters, and is the default.

Here are some EBCDIC examples:

DBADJUST('<.A><.B>a<>b','B')    ->    '<.A. .B>a  b'
DBADJUST('<.A><.B>a<>b','R')    ->    '<.A.B>ab'
DBADJUST('<><.A.B>','B')        ->    '<. .A.B>'

DBBRACKET

Read syntax diagramSkip visual syntax diagram>>-DBBRACKET(string)-------------------------------------------><
 

In EBCDIC, adds SO and SI brackets to a DBCS-only string. If string is not a BCS-only string, a SYNTAX error results. That is, the input string must be an even number of bytes in length and each byte must be a valid DBCS value.

Here are some EBCDIC examples:

DBBRACKET('.A.B')      ->    '<.A.B>'
DBBRACKET('abc')       ->    SYNTAX error
DBBRACKET('<.A.B>')    ->    SYNTAX error

DBCENTER

Read syntax diagramSkip visual syntax diagram>>-DBCENTER(string,length--+-------------------------+--)------><
                           '-,--+-----+--+---------+-'
                                '-pad-'  '-,option-'
 

returns a string of length length with string centered in it, with pad characters added as necessary to make up length. The default pad character is a blank. If string is longer than length, it is truncated at both ends to fit. If an odd number of characters are truncated or added, the right-hand end loses or gains one more character than the left-hand end.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBCENTER('<.A.B.C>',4)             ->    ' <.B> '
DBCENTER('<.A.B.C>',3)             ->    ' <.B>'
DBCENTER('<.A.B.C>',10,'x')        ->    'xx<.A.B.C>xx'
DBCENTER('<.A.B.C>',10,'x','Y')    ->    'x<.A.B.C>x'
DBCENTER('<.A.B.C>',4,'x','Y')     ->    '<.B>'
DBCENTER('<.A.B.C>',5,'x','Y')     ->    'x<.B>'
DBCENTER('<.A.B.C>',8,'<.P>')      ->    ' <.A.B.C> '
DBCENTER('<.A.B.C>',9,'<.P>')      ->    ' <.A.B.C.P>'
DBCENTER('<.A.B.C>',10,'<.P>')     ->    '<.P.A.B.C.P>'
DBCENTER('<.A.B.C>',12,'<.P>','Y') ->    '<.P.A.B.C.P>'

DBCJUSTIFY

Read syntax diagramSkip visual syntax diagram>>-DBCJUSTIFY(string,length--+-------------------------+--)----><
                             '-,--+-----+--+---------+-'
                                  '-pad-'  '-,option-'
 

formats string by adding pad characters between nonblank characters to justify to both margins and length of bytes length (length must be nonnegative). Rules for adjustments are the same as for the JUSTIFY function. The default pad character is a blank.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some examples:

DBCJUSTIFY('<><AA  BB><CC>',20,,'Y')
                                  ->   '<AA>    <BB>    <CC>'

DBCJUSTIFY('<><  AA    BB><  CC>',20,'<XX>','Y')
                                  ->   '<AAXXXXXXBBXXXXXXCC>'

DBCJUSTIFY('<><  AA    BB><  CC>',21,'<XX>','Y')
                                  ->   '<AAXXXXXXBBXXXXXXCC> '

DBCJUSTIFY('<><  AA    BB><  CC>',11,'<XX>','Y')
                                  ->   '<AAXXXXBB> '

DBCJUSTIFY('<><  AA    BB><  CC>',11,'<XX>','N')
                                  ->   '<AAXXBBXXCC> '

DBLEFT

Read syntax diagramSkip visual syntax diagram>>-DBLEFT(string,length--+-------------------------+--)--------><
                         '-,--+-----+--+---------+-'
                              '-pad-'  '-,option-'
 

returns a string of length length containing the leftmost length characters of string. The string returned is padded with pad characters (or truncated) on the right as needed. The default pad character is a blank.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBLEFT('ab<.A.B>',4)             ->    'ab<.A>'
DBLEFT('ab<.A.B>',3)             ->    'ab '
DBLEFT('ab<.A.B>',4,'x','Y')     ->    'abxx'
DBLEFT('ab<.A.B>',3,'x','Y')     ->    'abx'
DBLEFT('ab<.A.B>',8,'<.P>')      ->    'ab<.A.B.P>'
DBLEFT('ab<.A.B>',9,'<.P>')      ->    'ab<.A.B.P> '
DBLEFT('ab<.A.B>',8,'<.P>','Y')  ->    'ab<.A.B>'
DBLEFT('ab<.A.B>',9,'<.P>','Y')  ->    'ab<.A.B> '

DBRIGHT

Read syntax diagramSkip visual syntax diagram>>-DBRIGHT(string,length--+-------------------------+--)-------><
                          '-,--+-----+--+---------+-'
                               '-pad-'  '-,option-'
 

returns a string of length length containing the rightmost length characters of string. The string returned is padded with pad characters (or truncated) on the left as needed. The default pad character is a blank.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBRIGHT('ab<.A.B>',4)             ->    '<.A.B>'
DBRIGHT('ab<.A.B>',3)             ->    ' <.B>'
DBRIGHT('ab<.A.B>',5,'x','Y')     ->    'x<.B>'
DBRIGHT('ab<.A.B>',10,'x','Y')    ->    'xxab<.A.B>'
DBRIGHT('ab<.A.B>',8,'<.P>')      ->    '<.P>ab<.A.B>'
DBRIGHT('ab<.A.B>',9,'<.P>')      ->    ' <.P>ab<.A.B>'
DBRIGHT('ab<.A.B>',8,'<.P>','Y')  ->    'ab<.A.B>'
DBRIGHT('ab<.A.B>',11,'<.P>','Y') ->    '   ab<.A.B>'
DBRIGHT('ab<.A.B>',12,'<.P>','Y') ->    '<.P>ab<.A.B>'

DBRLEFT

Read syntax diagramSkip visual syntax diagram>>-DBRLEFT(string,length--+---------+--)-----------------------><
                          '-,option-'
 

returns the remainder from the DBLEFT function of string. If length is greater than the length of string, returns a null string.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBRLEFT('ab<.A.B>',4)             ->    '<.B>'
DBRLEFT('ab<.A.B>',3)             ->    '<.A.B>'
DBRLEFT('ab<.A.B>',4,'Y')         ->    '<.A.B>'
DBRLEFT('ab<.A.B>',3,'Y')         ->    '<.A.B>'
DBRLEFT('ab<.A.B>',8)             ->    ''
DBRLEFT('ab<.A.B>',9,'Y')         ->    ''

DBRRIGHT

Read syntax diagramSkip visual syntax diagram>>-DBRRIGHT(string,length--+---------+--)----------------------><
                           '-,option-'
 

returns the remainder from the DBRIGHT function of string. If length is greater than the length of string, returns a null string.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBRRIGHT('ab<.A.B>',4)             ->    'ab'
DBRRIGHT('ab<.A.B>',3)             ->    'ab<.A>'
DBRRIGHT('ab<.A.B>',5)             ->    'a'
DBRRIGHT('ab<.A.B>',4,'Y')         ->    'ab<.A>'
DBRRIGHT('ab<.A.B>',5,'Y')         ->    'ab<.A>'
DBRRIGHT('ab<.A.B>',8)             ->    ''
DBRRIGHT('ab<.A.B>',8,'Y')         ->    ''

DBTODBCS

Read syntax diagramSkip visual syntax diagram>>-DBTODBCS(string)--------------------------------------------><
 

converts all passed, valid SBCS characters (including the SBCS blank) within string to the corresponding DBCS equivalents. Other single-byte codes and all DBCS characters are not changed. In EBCDIC, SO and SI brackets are added and removed where appropriate.

Here are some EBCDIC examples:

DBTODBCS('Rexx 1988')      ->    '<.R.e.x.x. .1.9.8.8>'
DBTODBCS('<.A> <.B>')      ->    '<.A. .B>'
Note:
In these examples, the .x is the DBCS character corresponding to an SBCS x.

DBTOSBCS

Read syntax diagramSkip visual syntax diagram>>-DBTOSBCS(string)--------------------------------------------><
 

converts all passed, valid DBCS characters (including the DBCS blank) within string to the corresponding SBCS equivalents. Other DBCS characters and all SBCS characters are not changed. In EBCDIC, SO and SI brackets are removed where appropriate.

Here are some EBCDIC examples:

DBTOSBCS('<.S.d>/<.2.-.1>')     ->    'Sd/2-1'
DBTOSBCS('<.X. .Y>')            ->    '<.X> <.Y>'

Note:
In these examples, the .d is the DBCS character corresponding to an SBCS d. But the .X and .Y do not have corresponding SBCS characters and are not converted.

DBUNBRACKET

Read syntax diagramSkip visual syntax diagram>>-DBUNBRACKET(string)-----------------------------------------><
 

In EBCDIC, removes the SO and SI brackets from a DBCS-only string enclosed by SO and SI brackets. If the string is not bracketed, a SYNTAX error results.

Here are some EBCDIC examples:

DBUNBRACKET('<.A.B>')      ->    '.A.B'
DBUNBRACKET('ab<.A>')      ->    SYNTAX error

DBVALIDATE

Read syntax diagramSkip visual syntax diagram>>-DBVALIDATE(string--+------+--)------------------------------><
                      '-,'C'-'
 

returns 1 if the string is a valid mixed string or SBCS string. Otherwise, returns 0. Mixed string validation rules are:

  1. Only valid DBCS character codes
  2. DBCS string is an even number of bytes in length
  3. EBCDIC only -- Proper SO and SI pairing.

In EBCDIC, if C is omitted, only the leftmost byte of each DBCS character is checked to see that it falls in the valid range for the implementation it is being run on (that is, in EBCDIC, the leftmost byte range is from X'41' to X'FE').

Here are some EBCDIC examples:

z='abc<de'

DBVALIDATE('ab<.A.B>')          ->    1
DBVALIDATE(z)                   ->    0

y='C1C20E111213140F'X

DBVALIDATE(y)                   ->    1
DBVALIDATE(y,'C')               ->    0

DBWIDTH

Read syntax diagramSkip visual syntax diagram>>-DBWIDTH(string--+---------+--)------------------------------><
                   '-,option-'
 

returns the length of string in bytes.

The option controls the counting rule. Y counts SO and SI within mixed strings as one each. N does not count the SO and SI and is the default.

Here are some EBCDIC examples:

DBWIDTH('ab<.A.B>','Y')    ->    8
DBWIDTH('ab<.A.B>','N')    ->    6