Command Specific Syntax and Examples


Note:  In order to be brief, these command summaries do not explain every detail.  For more information, consult the main article, Full Mapping String Documentation.


Command Index


AQ

Insert Accent Quote into result string

AX

Perform Ansi to Hex character conversion

C

Center text in result string

CC

Set CASE C as default for character searches

CT

Set CASE T as default for character searches

D

Delete character columns from result string

DC

Delete character values from result string

DD

Perform Decimal to Decimal numeric conversion

DQ

Insert Double Quote into result string

DX

Perform Decimal to Hex numeric conversion

DV

Specify a Dynamic Variable as a mapping string item

EX

Perform EBCDIC to Hex character conversion

IC

Invert Case of result string

L

Left justify the result string

LC

Set result string to Lower Case

M

Move characters within result

P

Pad the result string on both sides

PL

Pad the result string on Left side

PR

Pad the result string on Right side

R

Right justify the result string

RA

Replace All

RC

Replace Characters via translation table

RL

Replace Left-most

RP

Repeat the result string

RR

Replace Right-most

RV

Reverse the contents of the result string

SC

Set result string to Sentence Case

S*

Generate Sequence number in Decimal and Hex – SD / SX 

SQ

Insert Single Quote into result string

SV

Specify a Set Variable as an external mapping string item

TC

Set result string to Title Case

T

Trim the result string on both sides

TL

Trim the result string on Left side

TR

Trim the result string on Right side

UC

Set result string to Upper Case

X

Exchange strings

XA

Perform Hex to Ansi character conversion

XD

Perform Hex to Decimal numeric conversion

XE

Perform Hex to EBCDIC character conversion

XX

Perform Hex to Hex numeric conversion

Z

Zero-suppress the result field


AQ  -  Insert Accent Quote into result string


Summary

Insert Accent Quote into result string

Command type

Modifying command; will not Auto-Copy

Case mod codes

Not applicable

Syntax


replication-factor


AQ  [ replication-factor ]


Decimal value indicating the number of accent quotes inserted.  If omitted, a one quote is inserted.  If specified as zero, no quotes are inserted.

Example command

C  P"@@@@@"  M`AQ 1+ AQ`

Source string

|ABCDE|

Result string

|`ABCDE`|

Remarks




This command is useful to insert one or more accent quotes when the outer M string is itself enclosed in accent quotes.  Since this command does not auto-copy, you must explicitly specify other values you want in the result string, as is done with the 1+ code in the example.



AX  -  Perform Ansi to Hex character conversion


Summary

Convert character data to its Ansi encoding as hex digits

Command type

Copying command; will Auto-Reference

Case mod codes

Codes  >  and  <  honored; codes  <>  and  ><  treated as  >

Syntax


column-reference


bypass-string

AX  [ bypass-string ]  column-reference


selects columns from source string, or from result string if dot notation is used


Characters in bypass-string are not converted, but are copied as-is to the result string

Example command

C  P'##=@@'  M"AX`-`1+"

Source string

|12-Lb|

Result string

|3132-4C62|

Remarks

Note ‘-’ was not converted but copied.  “L” converts to “4C”  instead of “4c”.

Default for hex digits > 9 is upper case.



C  -  Center text in result string


Summary

Current contents of result string are centered within a specified size

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


field-size

C  [ pad-character ]  field-size


1-character value used for padding; if omitted, blank padding done


new length of result field

Example command

C  P"@@@@@"  M"1+ C8"

Source string

|ABCDE|

Result string

|°ABCDE°°|

Remarks

If field-size results in odd amount of padding, shorter amount goes on left.

The ° symbol represents one blank.

To pad with asterisk, use  M"1+ C`*`8"



CC  -  Set CASE C as default for character searches


Summary

Sets case-sensitive CASE C mode for commands that do character comparisons

Command type

Case control; does not copy or modify result string

Case mod codes

Not applicable

Syntax

CC

Example command

C  P'@@=@@=@@'  M"CC 1+ RC`Aa=12`"

Source string

|AA,aa,BB|

Result string

|11,22,BB|

Remarks

To use CASE C mode on individual command codes, use C suffix on string:

C  P'@@=@@=@@'  M"1+ RC`Aa=12`C"

In absence of CC/CT or string suffix codes, PROFILE CASE option is used.



CT  -  Set CASE T as default for character searches


Summary

Sets case-insensitive CASE T mode for commands that do character comparisons

Command type

Case control; does not copy or modify result string

Case mod codes

Not applicable

Syntax

CT

Example command

C  P'@@@@'  M"CT 1+ RC`a=2`"

Source string

|AA,aa,BB|

Result string

|22,22,BB|

Remarks

To use CASE T mode on individual command codes, use T suffix on string:

C  P'@@@@'  M"1+ RC`a=2`T"

In absence of CC/CT or string suffix codes, PROFILE CASE option is used.



D  -  Delete character columns from result string


Summary

Delete specified character columns from current contents of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax column


column-reference

D  column-reference


selects columns from result string only, whether dot notation used or not

the column-reference cannot be omitted

Example command

C  P'@@@@'  M"1+ D2-3"

Source string

|AbcD|

Result string

|AD|

Remarks

D only applies to result string, not to source string.  The column-reference is always treated as if it used dot-notation (implying use of result string) even if dot is omitted.

Following command has same result:   C  P'@@@@'  M"1+ D.2-3"


Note:  If you perform several D commands in the same mapping string, the relative column numbers to the right of where you delete data will change with each D command.  To simplify this and avoid problems, do such multiple deletes in a right-to-left manner.



DC  -  Delete character values from result string


Summary

Delete one or more instances of specified types of characters from result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


character-deletion-list


column-reference

DC  character-deletion-list   [  column-reference  ]


a quoted string of the form 'characters'


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string may potentially be modified

Example command

C  P'=@@@@='  WORD  M"1+ DC`)(`"

Source string

|(AbCd)|

Result string

|AbCd|

Remarks

The characters are one or more individual characters to be removed, and may be specified in any order.



DD  -  Perform Decimal to Decimal numeric conversion


Summary

Copy decimal data and apply numeric formatting

Command type

Copying command; will Auto-Reference

Case mod codes

Disregarded

Syntax


{  DD |  left-to-right-cmd  |  right-to-left-cmd  }   [  format  ]   [  sign  ]  column-reference

left-to-right-cmd


nDD

right-to-left-cmd

DnD


n

A value from 1 to 9, indicating the relative position within the selected columns where the number is found after scanning for it, where 1 means first, and 9 means ninth.  When n is used as nDD, the scan for the numeric value is done in a left-to-right manner, and when n is used as DnD, the scan for the numeric value is done in a right-to-left manner.


If n value is omitted, the DD command expects the full selected column range to be a single decimal number and no scan is performed to locate the value.


format

[  w  ]  t


w -  width of result number;  w is required for format types F and Z, optional for type V If omitted for type V, w is assumed to be 1.  If omitted for types F and Z, w is taken as the same width of the original number as found in the source string.


t - format type code

format F is fixed-width with zero-fill or truncation on left

format Z is fixed-width with zero-suppression or truncation on left

format V is variable width with zero-fill on left; for V code, w means minimum width and a w value of 0 is allowed


sign

If sign code S is present, any leading + or sign found during processing will be retained and copied to result string.  If sign code S is absent, any leading + or signs are ignored.  Any spaces after the leading + or sign are considered to be part of the sign.


column-reference

selects columns from source string, or from result string if dot notation is used


Example command

C  P'###'  WORD  M"DD5Z1+"

Source string

|123|

Result string

|°°123|

Remarks

To produce |00123| use  M"DD5F1+"

The value 5 is the format length.

The ° symbol represents one blank.



DQ  -  Insert Double Quote into result string


Summary

Insert Double Quote into result string

Command type

Modifying command; will not Auto-Copy

Case mod codes

Not applicable

Syntax


replication-factor


DQ  [ replication-factor ]


Decimal value indicating the number of double quotes inserted.  If omitted, a one quote is inserted.  If specified as zero, no quotes are inserted.

Example command

C  P"@@@@@"  M"DQ 1+ DQ"

Source string

|ABCDE|

Result string

|"ABCDE"|

Remarks




This command is useful to insert one or more double quotes when the outer M string is itself enclosed in double quotes.  Since this command does not auto-copy, you must explicitly specify other values you want in the result string, as is done with the 1+ code in the example.



DV  -  Specify a Dynamic Variable as a mapping string item


Summary

The result string is used as a Dynamic Value of a mapping item

Command type

Modifying command; will Auto-Copy

Case mod codes

Disregarded

Syntax


delete-option











DV  [  delete-option  ]   column-reference


An optional quoted string operand.  If present, it contains a single letter specifying what is done with the result string prior to the DV command finishing.  

The letter is case-insensitive.


    • 'K'  means to keep the result string as-is without change.
    • 'D'  means to delete the portion of the result string that was referenced by the column-reference operand.  This is the default if the delete-option is omitted.
    • 'E'  means to erase the entire result string so that it contains a null (empty) string as it does when mapping string is first processed.



column-reference 

selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is used as the source of the new mapping command

Remarks

See the main Help article, Working with Mapping Strings for more information on this command.



DX  -  Perform Decimal to Hex numeric conversion


Summary

Convert decimal data to hex and apply numeric formatting

Command type

Copying command; will Auto-Reference

Case mod codes

Codes  >  and  <  honored; codes  <>  and  ><  treated as  >

Syntax


{  DX |  left-to-right-cmd  |  right-to-left-cmd  }   [  format  ]   [  sign  ]  column-reference


left-to-right-cmd

nDX


right-to-left-cmd

DnX


n

A value from 1 to 9, indicating the relative position within the selected columns where the number is found after scanning for it, where 1 means first, and 9 means ninth.  When n is used as nDX, the scan for the numeric value is done in a left-to-right manner, and when n is used as DnX, the scan for the numeric value is done in a right-to-left manner.


If n value is omitted, the DX command expects the full selected column range to be a single decimal number and no scan is performed to locate the value.


format

[  w  ]  t


w - width of result number;  w is required for format types F and Z, optional for type V

If omitted for type V, w is assumed to be 1.  If omitted for types F and Z, w is taken as the same width of the original number as found in the source string.


t - format type code

  • format F is fixed-width with zero-fill or truncation on left
  • format Z is fixed-width with zero-suppression or truncation on left
  • format V is variable width with zero-fill on left; for V code, w means minimum width and a w value of 0 is allowed


sign

If sign code S is present, any leading + or sign found during processing will be retained and copied to result string.  If sign code S is absent, any leading + or signs are ignored.  Any spaces after the leading + or sign are considered to be part of the sign.


column-reference

selects columns from source string, or from result string if dot notation is used


Example command

C  P'###'  WORD  M"DX2Z1+"

Source string

|015|

Result string

|0F|

Remarks

To produce | F| use  M"DX2F1+"

The value 2 is the format length.

See Working with Mapping Strings to Reorder, Reformat and Transform Data for a description of how the casing of hex digits > 9 is rendered.

       


EX  -  Perform EBCDIC to Hex character conversion


Summary

Convert character data to its EBCDIC encoding as hex digits

Command type

Copying command; will Auto-Reference

Case mod codes

Codes  >  and  <  honored; codes  <>  and  ><  treated as  >

Syntax


column-reference


bypass-string

EX  [ bypass-string ]  column-reference


selects columns from source string, or from result string if dot notation is used


Characters in bypass-string are not converted, but are copied as-is to the result string

Example command

C  P'##=@@'  M"EX`-`1+"

Source string

|12-Lb|

Result string

|F1F2-D383|

Remarks

Note ‘-’ was not converted but copied.  “L” converts to “D3” instead of “d3”.

Default for hex digits > 9 is upper case.  The EBCDIC translation used will be the standard 1140 code page, without regard to the SOURCE code page setting.



IC  -  Invert Case of result string


Summary

Inverts the case of the result string, as of the point the IC command is issued

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

IC  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is set to lower case

Example command

C  P'@@@@'  M"1+ IC"

Source string

|AAcc|

Result string

|aaCC|

Remarks




L  -  Left justify the result string


Summary

Left-justify contents of result string within a specified size

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


field-size

L  [ pad-character ]  field-size


1-character value used for padding; if omitted, blank padding done


new length of result field

Example command

C  P"@@@@@"  M"1+ L8"

Source string

|ABCDE|

Result string

|ABCDE°°°|

Remarks


The ° symbol represents one blank.

To pad with asterisk, use  M"1+ L`*`8"



LC  -  Set result string to Lower Case


Summary

Sets contents of result string to lower case, as of the point the LC command is issued

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

LC  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is set to lower case

Example command

C  P'@@@@'  M"1+ LC"

Source string

|AAcc|

Result string

|aacc|

Remarks




M - Move characters within result


Summary

Move data from one location to another within result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


destination-

reference






M  destination-reference  column-reference


    • when this is a single column number as n, it defines a column n within the result string where the data is to be moved into, with existing columns n and beyond being pushed to the right
    • when this is a single column number as x-y, it defines a column range within the result string where the data is to be moved into, with existing x-y columns being deleted
    • destination-reference may be end relative.  If specified as a lone * asterisk, data is moved to the end of the result string.

column-reference

selects columns from result string only, whether dot notation used or not

the column-reference cannot be omitted

Example command

C  R'[-A-Fa-f0-9]+'  WORD  M"1+ M`5`9-11"

Source string

|One/\TwoXyz|

Result string

|One/Xyz\Two|

Remarks

The Move command would be used when you need to rearrange the result string, or when the default of appending values to the end of the result string is not what you need.  The destination string `5` means the moved data is inserted at position 5 of the current result string, after the point where the "\" is located, and the remaining data is pushed to the right.


9-11 selects the "xyz" from the current result string.  These columns are deleted after their value is moved to the specified location.  Thus, if you move columns from the middle of the string to the end of it, you reference the column numbers as of prior to the move being performed.



P  -  Pad the result string on both sides


Summary

Add pad characters on both the left and right sides of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


pad-amount

P  [ pad-character ]  [ pad-amount ]


If omitted, the pad character is a single blank


Number of pad characters to be added to each side.  If omitted, 1 is assumed.

Example command

C  P'@@@@'  M"1+ P"

Source string

|AAcc|

Result string

|°AAcc°|

Remarks


The ° symbol represents one blank.

To pad with asterisk, use  M"1+ P`*`"



PL  -  Pad the result string on Left side


Summary

Add pad characters on left side of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


pad-amount

PL  [ pad-character ]  [ pad-amount ]


If omitted, the pad character is a single blank


Number of pad characters to be added to each side.  If omitted, 1 is assumed.

Example command

C  P'@@@@'  M"1+ PL"

Source string

|AAcc|

Result string

|°AAcc|

Remarks


The ° symbol represents one blank.

To pad with asterisk, use  M"1+ PL`*`"



PR  -  Pad the result string on Right side


Summary

Add pad characters on right side of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


pad-amount

PR  [ pad-character ]  [ pad-amount ]


If omitted, the pad character is a single blank


Number of pad characters to be added to each side.  If omitted, 1 is assumed.

Example command

C  P'@@@@'  M"1+ PR"

Source string

|AAcc|

Result string

|AAcc°|

Remarks


The ° symbol represents one blank.

To pad with asterisk, use  M"1+ PR`*`"



R  -  Right justify the result string


Summary

Right-justify contents of result string within a specified size

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


field-size

R  [ pad-character ]  field-size


1-character value used for padding; if omitted, blank padding done


new length of result field

Example command

C  P"@@@@@"  M"1+ R8"

Source string

|ABCDE|

Result string

|°°°ABCDE|

Remarks


The ° symbol represents one blank.

To pad with asterisk, use  M"1+ R`*`8"



RA  -  Replace All


Summary

Replace all instances of first string value with second string value

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy.  Otherwise, codes > and < honored;

codes <>  and >< disregarded in favor of explicit string type codes.

Syntax


RA  string-values  [  column-reference  ]

String-values

A quoted string of the form 'first =second' and may contain a string type code.

The first and second parts can be of different lengths; the second part can be null, but the first part cannot.  When second string is null, command acts to delete the first string.  The before and after parts cannot contain = equal signs as data if specified in the single string-values form.  


column-reference

selects columns from result string only, whether dot notation used or not

if omitted, the entire result string may potentially be modified

Example command

C  P'================='  WORD  M"RA`pay=taxes`"

Source string

|gross_pay,net_pay|

Result string

|gross_taxes,net_taxes|

Remarks





When characters to the left of = sign contain letters, see main article for explanation how the case of letters is handled.  The first and second parts can be specified as a string pair;  example:  M"RA`pay`=`taxes`".  When this is done, each part can have its own string type code of C, T or X, and can contain = equal signs as data.  A string value with a string-pair separator of “:” instead of “=” signifies a case-conformant change.  See section 9, Case sensitivity and case conformance, for an explanation of how type codes on string pairs are handled.



RC  -  Replace Characters via translation table


Summary

Modify result string by translating one set of characters with another

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy.  Otherwise, codes > and < honored;

codes <>  and >< disregarded in favor of explicit string type codes.

Syntax


character-replacement-list


column-reference

RC  character-replacement-list  [  column-reference  ]


a quoted string of the form 'before=after'

the before and after parts are strings of the same length


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string may potentially be modified

Example command

C  P'@@@@'  WORD  M"1+ RC`()db=[]42`"

Source string

|(AbCd)|

Result string

|[A2C4]|

Remarks

The relationship between characters on the left side of the = sign and the right side is positional.  Notice the ( is associated with [ ; the ) is associate with ] and so on.  The before and after parts cannot themselves contain = signs when these are part of a single value as in 'before=after'.


The before and after parts can also be specified as 'before'='after'.  Example:  M"1+ RC`123`=`xyz`".  When this is done, each part may optionally have its own string type code of C, T or X, and may contain embedded equal signs as data.  A string value with a string-pair separator of “:” instead of “=” signifies a case-conformant change.  See section 9, Case sensitivity and case conformance, for an explanation of how type codes on string pairs are handled.



RL  -  Replace Left-most


Summary

Replace left-most instance of first string value with second string value

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy.  Otherwise, codes > and < honored;

codes <>  and >< disregarded in favor of explicit string type codes.

Syntax


RL  string-values  [  column-reference  ]

String-values

A quoted string of the form 'first =second' and may contain a string type code.

The first and second parts can be of different lengths; the second part can be null, but the first part cannot.  When second string is null, command acts to delete the first string.  The before and after parts cannot contain = equal signs as data if specified in the single string-values form.  


column-reference

selects columns from result string only, whether dot notation used or not

if omitted, the entire result string may potentially be modified

Example command

C  P'================='  WORD  M"RL`pay=taxes`"

Source string

|gross_pay,net_pay|

Result string

|gross_taxes,net_pay|

Remarks





When characters to the left of = sign contain letters, see main article for explanation how the case of letters is handled.  The first and second parts can be specified as a string pair;  example:  M"RL`pay`=`taxes`".  When this is done, each part can have its own string type code of C, T or X, and can contain = equal signs as data.  A string value with a string-pair separator of “:” instead of “=” signifies a case-conformant change.  See section 9, Case sensitivity and case conformance, for an explanation of how type codes on string pairs are handled.



RP  -  Repeat the result string


Summary

Repeat the result string a specified number of times

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


replication-factor


RP  [  replication-factor  ]


A numeric value to indicate the number of times the result string is to be replicated; if omitted, a value of 1 is assumed.  If specified as zero, no replication occurs.

Example command

C  P"@@@  M"RP"

Source string

|Abc|

Result string

|AbcAbc|

Remarks


RP makes one or more copies of whatever is in the result string at the point RP is used.  The replication-factor specifies the number of additional copies of the result string are made.  Thus, after an RP2 command is issued, there will be 3 copies (2 additional ones) of the result string.



RR  -  Replace Right-most


Summary

Replace right-most instance of first string value with second string value

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy.  Otherwise, codes > and < honored;

codes <>  and >< disregarded in favor of explicit string type codes.

Syntax


RR  string-values  [  column-reference  ]


String-values

A quoted string of the form 'first =second' and may contain a string type code.

The first and second parts can be of different lengths; the second part can be null, but the first part cannot.  When second string is null, command acts to delete the first string.  The before and after parts cannot contain = equal signs as data if specified in the single string-values form.  


column-reference

selects columns from result string only, whether dot notation used or not

if omitted, the entire result string may potentially be modified

Example command

C  P'================='  WORD  M"RR`pay=taxes`"

Source string

|gross_pay,net_pay|

Result string

|gross_pay,net_taxes|

Remarks





When characters to the left of = sign contain letters, see main article for explanation how the case of letters is handled.  The first and second parts can be specified as a string pair;  example:  M"RR`pay`=`taxes`".  When this is done, each part can have its own string type code of C, T or X, and can contain = equal signs as data.  A string value with a string-pair separator of “:” instead of “=” signifies a case-conformant change.  See section 9, Case sensitivity and case conformance, for an explanation of how type codes on string pairs are handled.



RV  - Reverse the contents of the result string


Summary

Reverse the contents of the result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

RV  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is reversed

Example command

C  P'@@@'  M"`\` 1+ `/` RV"

Source string

|ABC|

Result string

|/CBA\|

Remarks

If RV were the only command, the result string would be CBA, due to auto-copy.  Because a reverse column reference can also reverse characters, the main use of RV is to reverse the result string (or part of it) after a complex value is built up from several commands.



SC  -  Set result string to Sentence Case


Summary

Sets contents of result string to Sentence Case, as of the point the SC command is issued

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

SC  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is set to sentence case

Example command

C  P'@@@ @@@'  M"1+ SC"

Source string

|ONE two|

Result string

|One two|

Remarks

See main help for a description (Primary and Line commands) of what Sentence Case means.



S*  -  Generate Sequence number in Decimal and Hex – SD / SX


Summary

SD - Convert sequence number to decimal and apply numeric formatting

SX - Convert sequence number to hex and apply numeric formatting

Command type

Modifying commands; will not Auto-Copy

Case mod codes

Codes  >  and  <  honored; codes  <>  and  ><  treated as  >

Syntax


{  SD |  SX  }   [  format  ]   [  sign  ]   [  calculation-operand  ]


format

[  w  ]  t


w - width of result number;  w is required for format types F and Z, optional for type V

If omitted for type V, w is assumed to be 1.  If omitted for types F and Z, w is taken as minimum size needed to format the number without truncation.


t - format type code

  • format F is fixed-width with zero-fill or truncation on left
  • format Z is fixed-width with zero-suppression or truncation on left
  • format V is variable width with zero-fill on left; for V code, w means minimum width and a w value of 0 is allowed



sign

If sign code S is present, any leading + or sign found during processing will be retained and copied to result string.  If sign code S is absent, any leading + or signs are ignored.  Any spaces after the leading + or sign are considered to be part of the sign. s


column-reference

selects columns from source string, or from result string if dot notation is used


Example command

C  R'[A-Za-z0-9_]+'  WORD  M"1+ '_' SD5F'*2 +1'"

Source string

|record_counter|

Sequence number

25

Result string

|record_counter_00501|

Remarks

The value 5 is the format length.

See Working with Mapping Strings to Reorder, Reformat and Transform Data for a description of how the casing of hex digits > 9 is rendered.



SQ  -  Insert Single Quote into result string


Summary

Insert Single Quote into result string

Command type

Modifying command; will not Auto-Copy

Case mod codes

Disregarded

Syntax


replication-factor


SQ  [ replication-factor ]


Decimal value indicating the number of single quotes inserted.  If omitted, a one quote is inserted.  If specified as zero, no quotes are inserted.

Example command

C  P"@@@@@"  M'SQ 1+ SQ'

Source string

|ABCDE|

Result string

|'ABCDE'|

Remarks




This command is useful to insert one or more single quotes when the outer M string is itself enclosed in single quotes.  Since this command does not auto-copy, you must explicitly specify other values you want in the result string, as is done with the 1+ code in the example.



SV  -  Specify a Set Variable as an external mapping string item


Summary

A named SPFLite SET Variable is used as a mapping item

Command type

Special case; does not copy or modify result string

Case mod codes

Disregarded

Syntax


symbol-name

SV  symbol-name


A quoted-string value naming an SPFLite SET variable.

Example command

C  P"##=##=##"  M"SV'ABC'"

Contents of

MAPSTR.SV.ABC

RC'*'='/'

Source string

12*34*56

Result string

12/34/56

Remarks


When you specify a symbol-name, a prefix is added to the name you supply.  If you issue a mapping command of SV'ABC',  the SPFLite SET variable that is searched for is  MAPSTR.SV.ABC.   The mapping commands retrieved from the SET variable are substituted at the point where they are referenced in your M string.



TC  -  Set result string to Title Case


Summary

Sets contents of result string to Title Case, as of the point the TC command is issued

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

TC  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is set to title case

Example command

C  P'@@@ @@@'  M"1+ TC"

Source string

|ONE two|

Result string

|One Two|

Remarks

See main help for a description (Primary and Line commands) of what Title Case means.



T  -  Trim the result string on both sides


Summary

Remove pad characters from both the left and right sides of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


maximum-trim

T  [ pad-character ]  [ maximum-trim ]


If omitted, the pad character being removed is a single blank


Maximum number of pad characters to be removed from each side.  If omitted, all possible padding characters are removed.

Example command

C  P'===@@@@==='  M"1+ T`*`"

Source string

|***AAcc***|

Result string

|AAcc|

Remarks

To remove just 1 asterisk on each side and produce |**AAcc**|, use  M"1+ T`*`1"



TL  -  Trim the result string on Left side


Summary

Remove pad characters from left side of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


maximum-trim

TL  [ pad-character ]  [ maximum-trim ]


If omitted, the pad character being removed is a single blank


Maximum number of pad characters to be removed from left side.  If omitted, all possible padding characters are removed from left side.

Example command

C  P'===@@@@==='  M"1+ TL`*`"

Source string

|***AAcc***|

Result string

|AAcc***|

Remarks

To remove just 1 asterisk on the left and produce |**AAcc***|, use  M"1+ TL`*`1"



TR  -  Trim the result string on Right side


Summary

Remove pad characters from right side of result string

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


pad-character


maximum-trim

TR  [ pad-character ]  [ maximum-trim ]


If omitted, the pad character being removed is a single blank


Maximum number of pad characters to be removed from right side.  If omitted, all possible padding characters are removed from right side.

Example command

C  P'===@@@@==='  M"1+ TR`*`"

Source string

|***AAcc***|

Result string

|***AAcc|

Remarks

To remove just 1 asterisk on the right and produce |***AAcc**|, use  M"1+ TR`*`1"



UC  -  Set result string to Upper Case


Summary

Sets contents of result string to Upper Case, as of the point the UC command is issued

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


column-reference

UC  [  column-reference  ]


selects columns from result string only, whether dot notation used or not

if omitted, the entire result string is set to upper case

Example command

C  P'@@@@'  M"1+ UC"

Source string

|AAcc|

Result string

|AACC|

Remarks




X  -  Exchange strings


Summary

If source string contains one of two values, exchange first with second or vice-verse

Command type

Copying command; will Auto-Reference

Case mod codes

Honored during auto-copy.  Otherwise, codes > and < honored;

codes <>  and >< disregarded in favor of explicit string type codes.

Syntax


exchange-pair


column-reference

X  exchange-pair  column-reference


'first=second'  or  'first'='second'


selects columns from source string, or from result string if dot notation is used

Example command

C  R'[a-z]+'  M"X`one=five`1+"

Source string

|one|

Result string

|five|

Remarks

If found source string is one the value five is appended to result string.

If found source string is five the value one is appended to result string.

If found source string is eight the value eight is appended to result string.


Use exchange-pair format 'first'='second' if first or second contain embedded = equal signs.  When characters of first string contain letters, see Working with Mapping Strings article for an explanation how the case of letters and string type-codes are handled.


 An exchange-pair with a trailing type code of T signifies a case-conformant change.



XA  -  Perform Hex to Ansi character conversion


Summary

Convert encoded hex digits to their corresponding Ansi character data

Command type

Copying command; will Auto-Reference

Case mod codes

All codes honored

Syntax


column-reference


bypass-string

XA  [ bypass-string ]  column-reference


selects columns from source string, or from result string if dot notation is used


Characters in bypass-string are not converted, but are copied as-is to the result string

Example command

C  P'====\-===='  M"XA`-`1+"

Source string

|3132-4C62|

Result string

|12-Lb|

Remarks

Note ‘-’ was not converted but copied.  After any bypassed characters are discounted, what remains must be an even number of hex-digit characters.  Hex digits > 9 are always recognized in case-insensitive mode.



XD  -  Perform Hex to Decimal numeric conversion


Summary

Convert hex data to decimal and apply numeric formatting

Command type

Copying command; will Auto-Reference

Case mod codes

Disregarded

Syntax

{  XD |  left-to-right-cmd  |  right-to-left-cmd  }   [  format  ]   [  sign  ]  column-reference


left-to-right-cmd

nXD


right-to-left-cmd

XnD


n

A value from 1 to 9, indicating the relative position within the selected columns where the number is found after scanning for it, where 1 means first, and 9 means ninth.  When n is used as nXD, the scan for the numeric value is done in a left-to-right manner, and when n is used as XnD, the scan for the numeric value is done in a right-to-left manner.


If n value is omitted, the XD command expects the full selected column range to be a single hex number and no scan is performed to locate the value.


format

[  w  ]  t


w - width of result number;  w is required for format types F and Z, optional for type V

If omitted for type V, w is assumed to be 1.  If omitted for types F and Z, w is taken as the same width of the original number as found in the source string.


t - format type code

format F is fixed-width with zero-fill or truncation on left

format Z is fixed-width with zero-suppression or truncation on left

format V is variable width with zero-fill on left; for V code, w means minimum width and a w value of 0 is allowed


sign

If sign code S is present, any leading + or sign found during processing will be retained and copied to result string.  If sign code S is absent, any leading + or signs are ignored.  Any spaces after the leading + or sign are considered to be part of the sign.


If sign code C is present, it is treated like sign code S is, with the following addition:  If a number contains a 0x or 0X prefix (used in C and similar languages), that prefix is considered to be part of the sign, and not part of the number.  The reason this is needed is that without this, a value like 0x12 might appear to be two numbers, 0 and 12, separated by a delimiter of “x”.


column-reference

selects columns from source string, or from result string if dot notation is used


Example command

C  P'=='  WORD  M"XD3Z1+"

Source string

|0F|

Result string

|°15|

Remarks

Hex digits > 9 are always recognized in case-insensitive mode.

The value 3 is the format length.

To produce |015| use  M"XD3F1+"

The ° symbol represents one blank.



XE  -  Perform Hex to EBCDIC character conversion


Summary

Convert encoded hex digits to their corresponding EBCDIC character data

Command type

Copying command; will Auto-Reference

Case mod codes

All codes honored

Syntax


column-reference


bypass-string

XE  [ bypass-string ]  column-reference


selects columns from source string, or from result string if dot notation is used


Characters in bypass-string are not converted, but are copied as-is to the result string

Example command

C  R'[-A-Fa-f0-9]+'  WORD  M"XE`-`1+"

Source string

|F1F2-D382|

Result string

|12-Lb|

Remarks

Note ‘-’ was not converted but copied.  After any bypassed characters are discounted, what remains must be an even number of hex-digit characters.  Hex digits > 9 are always recognized in case-insensitive mode.  The EBCDIC translation used will be the standard 1140 code page, without regard to the SOURCE code page setting.



XX  -  Perform Hex to Hex numeric conversion


Summary

Copy hex data and apply numeric formatting

Command type

Copying command; will Auto-Reference

Case mod codes

Codes  >  and  <  honored; codes  <>  and  ><  treated as  >

Syntax


{  XX |  left-to-right-cmd  |  right-to-left-cmd  }   [  format  ]   [  sign  ]  column-reference

left-to-right-cmd

nXX


right-to-left-cmd

XnX


n

A value from 1 to 9, indicating the relative position within the selected columns where the number is found after scanning for it, where 1 means first, and 9 means ninth.  When n is used as nXX, the scan for the numeric value is done in a left-to-right manner, and when n is used as XnX, the scan for the numeric value is done in a right-to-left manner.


If n value is omitted, the XX command expects the full selected column range to be a single hex number and no scan is performed to locate the value.


format

[  w  ]  t


w - width of result number;  w is required for format types F and Z, optional for type V

If omitted for type V, w is assumed to be 1.  If omitted for types F and Z, w is taken as the same width of the original number as found in the source string.


t - format type code

format F is fixed-width with zero-fill or truncation on left

format Z is fixed-width with zero-suppression or truncation on left

format V is variable width with zero-fill on left; for V code, w means minimum width and a w value of 0 is allowed


sign

If sign code S is present, any leading + or sign found during processing will be retained and copied to result string.  If sign code S is absent, any leading + or signs are ignored.  Any spaces after the leading + or sign are considered to be part of the sign.


If sign code C is present, it is treated like sign code S is, with the following addition:  If a number contains a 0x or 0X prefix (used in C and similar languages), that prefix is considered to be part of the sign, and not part of the number.  The reason this is needed is that without this, a value like 0x12 might appear to be two numbers, 0 and 12, separated by a delimiter of “x”.


column-reference

selects columns from source string, or from result string if dot notation is used


Example command

C  P'=='  WORD  M"XX3Z1+"


Source string

|0F|

Result string

|°0F|

Remarks

Hex digits > 9 are always recognized in case-insensitive mode.

The value 3 is the format length.

To produce |00F| use  M"XX3F1+"

The ° symbol represents one blank.



Z  -  Zero-suppress the result field


Summary

Zero-suppress a formatted decimal number

Command type

Modifying command; will Auto-Copy

Case mod codes

Honored during auto-copy, otherwise disregarded

Syntax


Z  [ ignore-characters ]  [ minimum-length ]


ignore-characters

one or more non-significant leading characters to be ignored/suppressed; typically will include comma (U.S. format) or dot (European format)


minimum-length

the right-most number of characters that will not be suppressed, regardless of content; if omitted, there is no minimum length, leading to possible suppression of entire field


Example command

C  P"#$###$##"  WORD  M"1+ Z','3"

Source string

|0,001.23|

Result string

|°°°°1.23|

Remarks

The ° symbol represents one blank.

Non-significant leading zeros and spaces are always ignored/suppressed

A value of |0,000.23| would result in |°°°°°.23|

A value of |0,000.03| would result in |°°°°°.03|




Created with the Personal Edition of HelpNDoc: Easily create PDF Help documents