3.5.3 COBW3_SET_CNV, COBW3_SET_CNV_XX, COBW3_SET_CNV_NX, COBW3_SET_CNV_XN, and COBW3_SET_CNV

These subroutines register a conversion result (conversion character string) that corresponds to a conversion name that is enclosed in "//COBOL//" on the processing result output Web page that is to be output by COBW3_PUT_HTML.

The registered information is referenced during the execution of COBW3_PUT_HTML. The conversion name in the processing result output Web page is converted according to the registered conversion data.

These subroutines have the following functions:

ASCII environment

COBW3_SET_CNV: Registers, as an alphanumeric character string, the conversion character string that corresponds to the conversion name, which is an alphanumeric character string.

Unicode environment

COBW3_SET_CNV_XX: Registers, as an alphanumeric character string, the conversion character string that corresponds to the conversion name, which is an alphanumeric character string.

COBW3_SET_CNV_NX: Registers, as an alphanumeric character string, the conversion character string that corresponds to the conversion name, which is a national character string.

COBW3_SET_CNV_XN: Registers, as a national character string, the conversion character string that corresponds to the conversion name, which is an alphanumeric character string.

COBW3_SET_CNV_NN: Registers, as a national character string, the conversion character string that corresponds to the conversion name, which is a national character string.

Note

If two or more different conversion names are specified in a Web page for processing result output, conversion character strings must be registered by calling COBW3_SET_CNV, etc. for each of these conversion names.

Format

CALL "COBW3_SET_CNV" USING COBW3.

CALL "COBW3_SET_CNV_XX" USING COBW3.

CALL "COBW3_SET_CNV_NX" USING COBW3.

CALL "COBW3_SET_CNV_XN" USING COBW3.

CALL "COBW3_SET_CNV_NN" USING COBW3.

Data setting at calling

COBW3-CNV-NAME and COBW3-CNV-NAME-N

Specify a conversion name that is to be converted.

When COBW3_SET_CNV, COBW3_SET_CNV_XX or COBW3_SET_CNV_XN are used, specify the name in COBW3-CNV-NAME.

When COBW3_SET_CNV_NX or COBW3_SET_CNV_NN are used, specify the name in COBW3-CNV-NAME-N.

COBW3-CNV-NAME-LENGTH [Optional]

To register a conversion name that has a valid blank at the end, specify the byte length of the name containing the blank (character string).

Value	Explanation
0	Retrieves a conversion name up to the last character other than the blank. However, if the COBW3-CNV-NAME or COBW3-CNV-NAME-N character string consists of only blank characters, the character string length is assumed to be 0.
1 to 30	Retrieves a conversion name of the specified character string length.

COBW3-CNV-VALUE and COBW3-CNV-VALUE-N

Specify a conversion result (conversion character string).

When COBW3_SET_CNV, COBW3_SET_CNV_XX or COBW3_SET_CNV_NX are used, specify the conversion character string in COBW3-CNV-VALUE.

When COBW3_SET_CNV_XN or COBW3_SET_CNV_NN are used, specify the conversion character string in COBW3-CNV-VALUE-N.

COBW3-CNV-VALUE-LENGTH [Optional]

When the conversion character string has a valid blank at the end, specify the byte length of the character string containing the blank.

Value	Explanation
0	Registers a conversion character string up to the last character other than the blank. However, if the COBW3-CNV-VALUE or COBW3-CNV-VALUE-N character string consists of only blank characters, the character string length is assumed to be 0.
1 to 1024	Registers a conversion character string of the specified character string length.

COBW3-CNV-MODE [Optional]

Specify a conversion mode.

Condition name	Value	Explanation
COBW3-CNV-MODE-ADDREP	LOW-VALUE	Adds conversion data if the specified conversion name was not registered.
COBW3-CNV-MODE-REPLACE	"1"	Replaces conversion data. If the specified conversion name was not registered, an abnormal end occurs (the conversion name is not converted).
COBW3-CNV-MODE-ADD	"2"	Adds conversion data. If the specified conversion name was already registered, an abnormal end occurs (the conversion data is not added).

Condition name

Value

Explanation

COBW3-CNV-MODE-ADDREP

LOW-VALUE

Adds conversion data if the specified conversion name was not registered.

COBW3-CNV-MODE-REPLACE

"1"

Replaces conversion data.

If the specified conversion name was not registered, an abnormal end occurs (the conversion name is not converted).

COBW3-CNV-MODE-ADD

"2"

Adds conversion data.

If the specified conversion name was already registered, an abnormal end occurs (the conversion data is not added).

COBW3_SANITIZE_CNV [Optional]

If characters that are vulnerable to a cross site scripting attack are found in conversion data, those characters are automatically replaced. This process is referred to as "sanitizing".

For more details on cross site scripting, refer to Appendix P, Security, in the NetCOBOL User's Guide.

COBW3_SANITIZE_CNV is valid when either COBW3_SET_CNV_XX or COBW3_SET_CNV_NX is used. However, if the code set is Unicode, COBW3_SANITIZE_CNV is also valid when COBW3_SET_CNV_XN or COBW3_SET_CNV_NN is used.

Condition name	Value	Explanation
COBW3-SANITIZE-CNV-OFF	LOW-VALUE	Does not sanitize.
COBW3-SANITIZE-CNV-ON	"1"	Sanitize.

Note

The sanitization procedure replaces the five characters that are vulnerable to a cross site scripting attack (&, <, >, ", ') with the following escape characters:

&  ->  &amp;
<  ->  &lt;
>  ->  &gt;
"  ->  &quot;
'  ->  &#39;

As a result, a single character is being replaced with 4-6 characters, increasing the length of the sanitized data. This means that, depending on the content of the unsanitized data, sanitizing data may cause the maximum data length (1024 bytes) set in the Web parameter VALUE to be exceeded. If this happens, the sanitized data is truncated automatically at 1024 bytes.

It is also possible that the escape characters themselves may be truncated. In this case, the vulnerable character is deleted, not replaced. An example is given below.

Example

The unsanitized data area is 1021 bytes long. The first 1020 bytes contain n characters that do not require sanitizing, but the last character is an ampersand ( & ).

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&    <- Last character is "&"
   |             1021 bytes                       |

After sanitizing, this becomes:

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&amp;
   |            1025 bytes                              |

This exceeds the 1024-byte limit, but truncating the data to 1024 bytes would interrupt the escape character string (&). For this reason, the ampersand is deleted instead of being replaced.

    xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx      <- Trailing "&" is deleted
   |          1020 bytes                        |

As a result, the actual length of the data is reduced to 1020 bytes.

Processing result data

COBW3_SANITIZED_CNV_FLAG

If COBW3_SANITIZE_CNV is set, a value that indicates whether or not the replacement procedure (sanitizing) actually took place is set.

COBW3_SANITIZED_CNV_FLAG is valid when either COBW3_SET_CNV_XX or COBW3_SET_CNV_NX is used. However, if the code set is Unicode, COBW3_SANITIZED_CNV_FLAG is also valid when COBW3_SET_CNV_XN or COBW3_SET_CNV_NN is used.

Condition name	Value	Explanation
COBW3-SANITIZED-CNV-NON	"0"	Did not sanitize.
COBW3-SANITIZED-CNV-EXIST	"1"	Sanitized.

3.5.3 COBW3_SET_CNV, COBW3_SET_CNV_XX, COBW3_SET_CNV_NX, COBW3_SET_CNV_XN, and COBW3_SET_CNV_NN