# tibemsMapMsg_Set

Function

## Purpose

Set a name-value pair in a map message.

## Single Value C Declarations

    tibems_status tibemsMapMsg_SetBoolean(
        tibemsMapMsg message,
        const char* name,
        tibems_bool value );

    tibems_status tibemsMapMsg_SetByte(
        tibemsMapMsg message,
        const char* name,
        tibems_byte value );

    tibems_status tibemsMapMsg_SetChar(
        tibemsMapMsg message,
        const char* name,
        tibems_wchar value );

    tibems_status tibemsMapMsg_SetDouble(
        tibemsMapMsg message,
        const char* name,
        tibems_double value );

    tibems_status tibemsMapMsg_SetFloat(
        tibemsMapMsg message,
        const char* name,
        tibems_float value );

    tibems_status tibemsMapMsg_SetInt(
        tibemsMapMsg message,
        const char* name,
        tibems_int value );

    tibems_status tibemsMapMsg_SetLong(
        tibemsMapMsg message,
        const char* name,
        tibems_long value );

    tibems_status tibemsMapMsg_SetShort(
        tibemsMapMsg message,
        const char* name,
        tibems_short value );

    tibems_status tibemsMapMsg_SetString(
        tibemsMapMsg message,
        const char* name,
        const char* value );

## Array C Declarations

    tibems_status tibemsMapMsg_SetDoubleArray(
        tibemsMapMsg message,
        const char* name,
        const tibems_double* value,
        tibems_uint count );

    tibems_status tibemsMapMsg_SetFloatArray(
        tibemsMapMsg message,
        const char* name,
        const tibems_float* value,
        tibems_uint count );

    tibems_status tibemsMapMsg_SetIntArray(
        tibemsMapMsg message,
        const char* name,
        const tibems_int* value,
        tibems_uint count );

    tibems_status tibemsMapMsg_SetLongArray(
        tibemsMapMsg message,
        const char* name,
        const tibems_long* value,
        tibems_uint count );

    tibems_status tibemsMapMsg_SetShortArray(
        tibemsMapMsg message,
        const char* name,
        const tibems_short* value,
        tibems_uint count );

## Nested Message C Declarations

    tibems_status tibemsMapMsg_SetMapMsg(
        tibemsMapMsg message,
        const char* name,
        tibemsMsg mapMsg,
        tibems_bool takeOwnership );

    tibems_status tibemsMapMsg_SetStreamMsg(
        tibemsMsg message,
        const char* name,
        tibemsMsg streamMsg,
        tibems_bool takeOwnership);

## COBOL Call

    CALL "tibemsMapMsg_SetBoolean"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetByte"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetChar"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetDouble"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetDoubleArray"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               BY VALUE count,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetFloat"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetFloatArray"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               BY VALUE count,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetInt"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetIntArray"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               BY VALUE count,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetLong"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetLongArray"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               BY VALUE count,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetMapMsg"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE mapMsg,
               BY VALUE tibems-Boolean,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetShort"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE value,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetShortArray"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               BY VALUE count,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetStreamMsg"
         USING BY VALUE message,
               BY REFERENCE name,
               BY VALUE streamMsg,
               BY VALUE tibems-Boolean,
               RETURNING tibems-status
    END-CALL.

    CALL "tibemsMapMsg_SetString"
         USING BY VALUE message,
               BY REFERENCE name,
               BY REFERENCE value,
               RETURNING tibems-status
    END-CALL.

Note: `message`, `streamMsg` and `mapMsg` have usage pointer.

## Parameters

Parameter | Description
--- | ---
`message` | Set the pair in the body of this map message.
`name` | Set the pair with this name. Field names must not be null, and must not be empty strings.
`value` | Associate this value with the name.
`count` | Array functions set array values of this size (must be a positive number).
`mapMsg` | `tibemsMapMsg_SetMapMsg` sets this map message as a nested value.
`takeOwnership` | Nested message functions use this parameter to control ownership of nested messages. When this argument is `TIBEMS_TRUE`, the call increments the reference count of the nested message. This action prevents other calls from destroying the nested message improperly. We recommend that all calls supply `TIBEMS_TRUE`.

## Remarks

The JMS specification defines functions to set name-value pairs in a `MapMessage`.

## Extensions

Array functions and nested message functions extend the JMS specification. Use them only with SmartSockets or Rendezvous messages. Programs that use these extensions might be non-compliant, and cannot interoperate with other JMS providers.

## See Also

`tibemsMapMsg_Get`

`tibemsMapMsg_SetBytes`

Copyright © Cloud Software Group, Inc. All rights reserved.