&DECODE

The &DECODE verb decodes all or part of an MDO, creating logical ASN.1 components from a serial byte string.

This verb has the following format:

&DECODE MDO=targetmdo
      [ { [ TRANSLATE={ NO | ISO | DEC | ASCII } ]
            SRC_CHARSET=name
          [ TGT_CHARSET=name ]
          [ SINGLE_SUB=xx ]
          [ DOUBLE_SUB=xxxx ] } ]
      [ TRANSFER={ NO | BER } ]
      [ FROM MDO=sourcemdo ]

An NCL procedure can decode all or part of an MDO from a serial byte stream, after transmission using the &DECODE verb.

Operands:

MDO=targetmdo

(Mandatory) It identifies the target component for the decode operation. The target MDO name is:

A stem name (for example, MDO=ROSE) indicating that the target is an entire MDO
A compound name (for example, MDO=CMIP.GETARG) indicating that the target is a component within the MDO

In both cases, the MDO must exist and be mapped, or the request fails.

TRANSLATE={ NO | ISO | DEC | ASCII }

(Optional) Specifies the translation of character strings. If TRANSLATE=NO is specified, or defaulted, no character set translation occurs. Otherwise, character strings are translated using the character set specified by this operand.

During translation, all character codes are assumed to be from the indicated character set and are translated to their EBCDIC equivalent. Source graphic characters that do not have an equivalent translation are translated to blanks. Control characters are translated to nulls. When used with a transfer syntax, translation takes place after decoding. When used without a transfer syntax, no source MDO is specified and the target MDO is modified in place.

Specification of this operand precludes the use of SRC_CHARSET, TGT_CHARSET, SINGLE_SUB, and DOUBLE_SUB.

SRC_CHARSET=name

(Optional) Names the source character set. If this operand is specified, the TRANSLATE operand cannot be specified.

Use SRC_CHARSET instead of TRANSLATE to specify translation using the Advanced Translation Facility (ATF).

TGT_CHARSET=name

(Optional) Names the target character set. If this operand is specified, the TRANSLATE operand cannot be specified.

TGT_CHARSET defaults to SOLVE. However, you can specify any other character set name to indicate that you want to translate to that character set.

SINGLE_SUB=xx

(Optional) Specifies an overriding target one-byte substitution character. The value is in two hexadecimal characters. For example, to replace all untranslatable characters with an EBCDIC question mark, code SINGLE_SUB=3F (assuming TGT_CHARSET=ASCII).

DOUBLE_SUB=xxxx

(Optional) Specifies an overriding target two-byte substitution character. The value is in four hexadecimal characters.

TRANSFER={ NO | BER }

(Optional) Specifies the use of transfer syntax when decoding. If NO is specified, or defaulted, no decoding takes place. TRANSFER=BER indicates the use of Basic Encoding Rules as the transfer syntax.

When a transfer syntax is specified, the FROM operand is required to indicate the sourcemdo, which is treated as a serial byte stream. Decoding takes place in accordance with the definition of the target MDO, and the result is placed into the target MDO. If translation was also requested (by specifying the TRANSLATE operand), translation of the target component character strings occurs after decoding.

If the TRANSFER operand is omitted, or TRANSFER=NO is specified, no decoding takes place, and the FROM keyword and source MDO cannot be specified.

FROM MDO=sourcemdo

This operand is mandatory and identifies the source component for the decode operation. The source MDO name is:

A stem name (for example, MDO=ROSE) indicating that the source is an entire MDO
A compound name (for example, MDO=CMIP.GETARG) indicating that the source is a component within the MDO

Return Codes:

&RETCODE	&ZFDBK	Meaning
0	0	All data successfully decoded
4	0	Input was empty-no data was decoded
	1	Unexpected trailing octets were ignored
	2	End-of-contents octets were assumed
8	1	Data invalid, could not be decoded
	2	Mandatory component missing
	3	Expected tag not found
	4	Invalid length encoding
	5	Invalid tag encoding
	6	Invalid contents encoding
	7	Incorrect multiple tagging
	8	Incorrect recurring tag (within a SEQUENCE OF or SET OF type)
	9	Tag value exceeds implementation limit
	10	Length value exceeds implementation limit
	11	Data value exceeds implementation limit
12	0	Undefined MDO name referenced

For &RETCODE 4, the &SYSMSG variable contains a warning message describing the condition.

For &RETCODE 8, the &SYSMSG variable contains an error message describing the component in error, the position in the data stream where the error was encountered, and the actual error condition.

Notes:

When communicating with other open systems, it is necessary to encode data for transmission in a manner understood by both parties. This means that both systems need only agree on the format of the transmitted data, and not how that data is processed or kept locally in each system.
A transfer syntax describes the format of the transmitted data. The transfer syntax formally defines the rules for converting an abstract data structure as defined by the abstract syntax into a serial data stream.

Mapping Services uses Abstract Syntax Notation One (ASN.1), defined by ISO 8824 as the abstract syntax used to describe data structures within your product region. It also uses Basic Encoding Rules (BER) defined by ISO 8825, as the transfer syntax used to serialize data for transmission.

Using the &ENCODE verb, an NCL procedure can encode all, or part of an MDO, into a serial byte stream, ready for transmission. Often, this process must take place in stages, as some ASN.1 structures require that various substructures are already encoded elsewhere before the structure itself is encoded. To cater for this requirement, encoding takes place from one MDO to another. When all encoding is complete the final MDO is transmitted as a serial byte stream.

The &DECODE verb provides the reverse process, creating the logical ASN.1 components from a serial byte stream.

In addition to the serialization of data for transmission, the &ENCODE and &DECODE verbs provide the ability to translate between the ASN.1 defined character sets into the local format, EBCDIC.
Use of some operands implies the use of Advanced Translation Facility (ATF) for translation.

Example1:

&DECODE MDO=CMIP.GETARG TRANSLATE=DEC

&DECODE MDO=ROSE TRANSLATE=ISO TRANSFER=NO

In these examples, components present in targetmdo, and defined as ASN.1 character strings, are translated from the indicated character set to their EBCDIC equivalent.

Example 2:

&DECODE MDO=CMIP.GETARG TRANSFER=BER FROM +
        MDO=ROSE.RDIVAPDU

&DECODE MDO=ROSE TRANSLATE=NO TRANSFER=BER FROM +
        MDO=BYTESTR

&DECODE MDO=ROSE TRANSLATE=DEC TRANSFER=BER FROM +
        MDO=BYTESTR

These examples show decoding of a serial byte stream into targetmdo, with character string translation from the indicated character set, if any, to EBCDIC.

Example 3:

&DECODE MDO=BUD SRC_CHARSET=UNICODE

This example translates character data in the MDO BUD from Unicode to EBCDIC.

More information:

Code Page Selection

&ENCODE