ASBITSTREAM function

The ASBITSTREAM field function generates a bit stream for the subtree of a given field according to the rules of the parser that owns the field, and uses parameters supplied by the caller for:
  • Encoding
  • CCSID
  • Message set
  • Message type
  • Message format
  • Options
This function effectively removes the limitation of the existing BITSTREAM function, which can be used only on a tree produced by a parser belonging to an input node

The BITSTREAM function is retained only for backward compatibility.

SYNTAX

Notes:
  1. Each clause can occur once only

ASBITSTREAM returns a value of type BLOB containing a bitstream representation of the field pointed to by FieldReference and its children

The algorithm for doing this varies from parser to parser and according to the options specified. All parsers support the following modes:
  • RootBitStream, in which the bitstream generation algorithm is the same as that used by an output node. In this mode, a meaningful result is obtained only if the field pointed to is at the head of a subtree with an appropriate structure.
  • EmbeddedBitStream, in which not only is the bitstream generation algorithm the same as that used by an output node, but also the
    • Encoding
    • CCSID
    • Message set
    • Message type
    • Message format
    are determined, if not explicitly specified, in the same way as the output node. That is, they are determined by searching the previous siblings of FieldReference on the assumption that they represent headers.

    In this way, the algorithm for determining these properties is essentially the same as that used for the BITSTREAM function.

Some parsers also support another mode, FolderBitStream, which generates a meaningful bit stream for any subtree, provided that the field pointed to represents a folder.

In all cases, the bit stream obtained can be given to a CREATE statement with a PARSE clause, using the same DOMAIN and OPTIONS to reproduce the original subtree.

When the function is called, any clause expressions are evaluated. An exception is thrown if any of the expressions do not result in a value of the appropriate type.

If any parameter is NULL the result is NULL.

Clause Type Default value
Options integer RootBitStream & ValidateNone
Encoding integer 0
Ccsid integer 0
Message set character Zero length string
Message type character Zero length string
Message format character Zero length string

Although the OPTIONS clause accepts any expression that returns a value of type integer, it is only meaningful to generate option values from the list of supplied constants, using the BITOR function if more than one option is required.

Once generated, the value becomes an integer and can be saved in a variable or passed as a parameter to a function, as well as being used directly in an ASBITSTREAM call. The list of globally-defined constants is:
        Validate master options...
        ValidateContentAndValue
        ValidateValue		  -- Can be used with ValidateContent
        ValidateContent		-- Can be used with ValidateValue
        ValidateNone

        Validate failure action options...
        ValidateException
        ValidateExceptionList
        ValidateLocalError
        ValidateUserTrace

        Validate value constraints options...
        ValidateFullConstraints
        ValidateBasicConstraints

        Validate fix up options...
        ValidateFullFixUp
        ValidateNoFixUp
Notes:
  1. The validateFullFixUp option is reserved for future use. Selecting validateFullFixUp gives identical behaviour to validateNoFixUp.
  2. The validateFullConstraints option is reserved for future use. Selecting validateFullConstraints gives identical behaviour to validateBasicConstraints.
  3. For full details of the validation options, refer to Validation properties for messages in the MRM domain.

C and Java equivalent APIs

Note that equivalent options are not available on:
  • The Java plugin node API MBElement methods createElementAsLastChildFromBitstream() and toBitstream()
  • The C plugin node API methods cniCreateElementAsLastChildFromBitstream() and cniElementAsBitstream.

Only one option from each group can be specified, with the exception of ValidateValue and ValidateContent, which can be used together to obtain the content and value validation. If you do not specify an option within a group, the option in bold is used.

The ENCODING clause accepts any expression that returns a value of type integer. However, it is only meaningful to generate encoding values from the list of supplied constants:
       0
       MQENC_INTEGER_NORMAL
       MQENC_INTEGER_REVERSED
       MQENC_DECIMAL_NORMAL
       MQENC_DECIMAL_REVERSED
       MQENC_FLOAT_IEEE_NORMAL
       MQENC_FLOAT_IEEE_REVERSED
       MQENC_FLOAT_S390
0 uses the queue manager's encoding.

The values used for the CCSID clause follow the normal numbering system. For example, 1200 = UCS-2, 1208 = UTF-8.

In addition the following special values are supported:
       0
       -1
0 uses the queue manager's CCSID and -1 uses the CCSID's as determined by the parser itself. This value is reserved.

For absent clauses, the given default values are used. Use the CCSID and encoding default values, because they take their values from the queue manager's encoding and CCSID settings.

Similarly, use the default values for each of the message set, type, and format options, because many parsers do not require message set, type, or format information; any valid value is sufficient.

When any expressions have been evaluated, the appropriate bit stream is generated.
Note: Because this function has a large number of clauses, an alternative syntax is supported in which the parameters are supplied as a comma-separated list rather than by named clauses. In this case the expressions must be in the following order:
ENCODING -> CCSID -> SET -> TYPE -> FORMAT -> OPTIONS

The list can be truncated at any point and you can use an empty expression for any clauses for which you do not supply a value.

Examples

      DECLARE options INTEGER BITOR(FolderBitStream, ValidateContent, 
                                    ValidateValue);
      SET result = ASBITSTREAM(cursor OPTIONS options CCSID 1208);
      SET Result = ASBITSTREAM(Environment.Variables.MQRFH2.Data,,1208
                               ,,,,options);
Related concepts
ESQL overview
Related tasks
Developing ESQL
Handling large XML messages
Working with XML messages and bit streams
Related reference
Syntax diagrams: available types
ESQL field functions
BITSTREAM function (deprecated)
Supported code pages