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.

The ASBITSTREAM field function uses parameters supplied by the caller for:

Encoding
CCSID
Message set
Message type
Message format
Options

The ASBITSTREAM function removes the limitation of the existing BITSTREAM function, which can be used only on a tree produced by a parser that belongs to an input node.

The BITSTREAM function is retained only for compatibility with earlier versions.

Syntax

Note that each clause can occur once only.

ASBITSTREAM returns a value of type BLOB that contains a bitstream representation of the field that is 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 algorithm that generates the bit stream is the same as the algorithm that is 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 algorithm that generates the bit stream the same as the algorithm 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 that is 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
SET	Character	Zero length string
TYPE	Character	Zero length string
FORMAT	Character	Zero length string

For details of the syntax of the TYPE clause, refer to Specifying namespaces in the Message property.

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.

The generated value becomes an integer and can be saved in a variable, passed as a parameter to a function, or 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

For full details of the validation options, refer to Validation properties.

Note that not all the equivalent options are available in the C and Java™ equivalent APIs:

Equivalent validation options are not available in the C plugin node API methods cniCreateElementAsLastChildFromBitstream() and cniElementAsBitstream().
The Java plugin node API MBElement methods createElementAsLastChildFromBitstream() and toBitstream() provide validation options. However, the FolderBitStream and EmbeddedBitStream modes are not available. The only available mode is RootBitStream, which is the default value.

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 that are used for the CCSID clause follow the normal numbering system. For example, 1200 = UCS-2, 1208 = UTF-8.

In addition the special values 0 and -1 are supported:

0 uses the queue manager's CCSID
-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);