Attachment Layout for TIBCO Rendezvous

Overview of Attachment Layout for TIBCO Rendezvous

An attachment consists of multiple physical messages. Each physical message has a specific message type. The field name of the first field in each message specifies the message type. Subsequent fields in the same message should use the same field name.

Data Message Layout

The following table shows the field name and purpose of the "MSG," or "DATA," type.
Note: The message type "MSG," or "DATA," can be retrieved without a field ID. All other message types must use a field ID.
Fields for the Data Message Layout
Field Name
Purpose
"MSG" or "DATA"
message data sent using a map

Data Set Attachment Layout

All attachments are required to have an attachment header and a "LST" message. However, not all messages are required. For example, many data sets do not use integrity constraints or indexes. If a data set does not contain the information that is contained in a message type, then the message is not required to be sent. The following table shows the field name, the purpose of each message type, and the order in which messages should be sent for a data set.
Fields for the Data Set Attachment Layout
Field Name
Purpose
"HDR"
attachment header
"MSG" or "DATA"
message data sent using a map
"DAT"
data set descriptor
"VAR"
variable definition for data set
"ATO"
data set observations
"ATI"
data set index
"ATC"
data set integrity constraints
"LST"
last message of attachment

External File Attachment Layout

All attachments are required to have an attachment header and a "LST" message. However, not all messages are required. For each "FDC" record, send either a text file or a binary file. You can send more than one file in an attachment. Each file must have an "FDC" message and then one of the following:
  • one or more "ATX" messages for the text files
  • one or more "ATB" messages for the binary files
The following table shows the field name, the purpose of each message type, and the order in which messages should be sent for an external file.
Fields for the External File Attachment Layout
Field Name
Purpose
"HDR"
attachment header
"FDC"
external file descriptor
"ATX"
text file attachment body
"ATB"
binary file attachment body
"LST"
last message of attachment
The following sections contain the description and required format for each message type.

Message Data - "MSG" or "DATA"

Note: The message type "MSG," or "DATA," can be retrieved without a field ID. All other message types must use a field ID.
If any message data is to be sent along with an attachment, that message is sent following the attachment header. The field name for this type of message is either "MSG" or "DATA." The following sample is based on the map that is used in the code example provided on the Common Messaging Interface documentation.
The map for this message is described as: 'SHORT;LONG;DOUBLE;CHAR,,50'.
The following table shows the data values for the message data.
Data Values for the Message Data
Parameter
Value
parm1
100;
parm2
9999;
parm3
9999.1234;
parm4
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"; (blank padded to 50)
The following table shows the data type values for the message data.
Data Types for the Message Data
Data Type
Value
Description
short
1
add with tibrvMsg_AddI16()
long
2
add with tibrvMsg_AddI32() as appropriate
double
3
add with tibrvMsg_AddF64()
string(char)
4
add with tibrvMsg_AddString()
The following table shows the layout of the message data.
Fields for the Message Data
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
The number of data pieces to follow. For this example, the value of the field is "4".
2
int
tibrvMsg_AddI32()
The data type of the first data item. Because this data item is a short, the value for this field is "1".
3
short
tibrvMsg_AddI16()
The actual value of the first parameter being sent. In this case, because it is a short, the value is added to the message by using tibrvMsg_AddI16(). The value for this field is "100".
For each parameter that is sent, repeat fields 2 and 3 in the previous table, setting the appropriate values and incrementing the field IDs.

Attachment Header - "HDR"

The beginning of an attachment is recognized by processing the attachment header message. This message type is recognized by the "HDR" field name in all fields.
The following table shows the layout of the attachment header.
Note: All character strings are null terminated.
Fields for the Attachment Header
Field ID
Field Type
Function
Description
1
byte[24]
tibrvMsg_AddString()
header correlid: can be set to all blanks
2
unsigned long
tibrvMsg_AddU32()
reserved: set to 0
3
byte[24]
tibrvMsg_AddString()
reserved: set to all blanks
4
byte[24]
tibrvMsg_AddString()
message correlid: can be set to all blanks
5
integer
tibrvMsg_AddI32()
number of attachments in message (1 per data set)
6
integer
tibrvMsg_AddI32()
attachment type: value is
  • "1" for SAS data set.
  • "2" for an external text file
  • "3" for an external binary file
7
byte[24]
tibrvMsg_AddString()
attachment correlid: can be set to all blanks
8
int
tibrvMsg_AddI32()
length of qualifier 1 in field 9
9
char[]
tibrvMsg_AddString()
qualifier 1:
  • external files: designates the sending file specification "FILENAME" or "FILEREF"
  • data set: designates the sending library name
10
int
tibrvMsg_AddI32()
length of qualifier 2 in field 11
11
char[]
tibrvMsg_AddString()
qualifier 2:
  • external files: designates the sending filename or fileref
  • data set: designates the sending member name
12
int
tibrvMsg_AddI32()
length of attachment description
13
char[]
tibrvMsg_AddString()
attachment description
14
int
tibrvMsg_AddI32()
user-specified minor version number
15
int
tibrvMsg_AddI32()
user-specified major version number
For each attachment in the list, repeat fields 6-15 in the previous table, incrementing the field ID each time.
The attachment header is usually followed by the subordinate messages that contain the information necessary to re-create the data set or the external file.

Data Set Definition - "DAT"

The data set definition message is sent following the message data. This message type is recognized by the "DAT" field name in all fields.
The following table shows the layout of the data set definition.
Note: All character strings are null terminated.
Fields for the Data Set Definition
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
type of record is data set definition= 1
2
int
tibrvMsg_AddI32()
version information or 0
3
long
tibrvMsg_AddI32()
data set type length
4
char[]
tibrvMsg_AddString()
data set type
5
long
tibrvMsg_AddI32()
data set label length
6
char[]
tibrvMsg_AddString()
data set label
7
long
tibrvMsg_AddI32()
number of observations
8
long
tibrvMsg_AddI32()
number of variables
9
long
tibrvMsg_AddI32()
observation length
10
long
tibrvMsg_AddI32()
length of compress
11
char[]
tibrvMsg_AddString()
compress
12
char
tibrvMsg_AddString()
reuse ("R" or "E")
13
long
tibrvMsg_AddI32()
length of encrypt
14
char[]
tibrvMsg_AddString()
encrypt
15
long
tibrvMsg_AddI32()
number of variables in sort key
16
long
tibrvMsg_AddI32()
length of sort collating sequence or 1
17
char[]
tibrvMsg_AddString()
sort collating sequence or NULL
18
short
tibrvMsg_AddI16()
sort flags or 0
19
int
tibrvMsg_AddI32()
Read password flag
20
byte[4]
tibrvMsg_AddOpaque()
Read password (encrypted)
21
int
tibrvMsg_AddI32()
Write password flag
22
byte[4]
tibrvMsg_AddOpaque()
Write password (encrypted)
23
int
tibrvMsg_AddI32()
Alter password flag
24
byte[4]
tibrvMsg_AddOpaque()
Alter password (encrypted)
25
int
tibrvMsg_AddI32()
max_gen data set attribute

Variable Definition - "VAR"

The variable definition message is sent following the data set definition message. This message type is recognized by the "VAR" field name in all fields.
The following table shows the layout of the variable definition.
Note: All character strings are null terminated.
Fields for the Variable Definition
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
number of variables
2
int
tibrvMsg_AddI32()
type of record is variable definition=2
3
long
tibrvMsg_AddI32()
length of variable name
4
char[]
tibrvMsg_AddString()
name of variable
5
long
tibrvMsg_AddI32()
length of format name
6
char[]
tibrvMsg_AddString()
format name
7
long
tibrvMsg_AddI32()
length of informat name
8
char[]
tibrvMsg_AddString()
informat name
9
long
tibrvMsg_AddI32()
length of variable label
10
char[]
tibrvMsg_AddString()
variable label
11
char
tibrvMsg_AddString()
type of variable (1=numeric, 2=char)
12
long
tibrvMsg_AddI32()
length of variable
13
long
tibrvMsg_AddI32()
format field length
14
long
tibrvMsg_AddI32()
format decimal
15
long
tibrvMsg_AddI32()
informat field length
16
long
tibrvMsg_AddI32()
informat decimal
17
char
tibrvMsg_AddString()
nsort information
For each variable, repeat the fields in the previous table.
Note: If definitions are larger than 32K, then variable messages might span multiple physical messages.

Data Set Observations - "ATO"

The data set observations message is sent following the variable definition message. This message type is recognized by the "ATO" field name in all fields.
The following table shows the layout of the data set observations.
Note: All character strings are null terminated.
Fields for Data Set Observations
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
number of observations
2
int
tibrvMsg_AddI32()
type of record is observation = 3
3
int
tibrvMsg_AddI32()
observation type (vtype)
4
double-observation
tibrvMsg_AddF64()
if observation type in field 3 is numeric
4
char[] - observation
tibrvMsg_AddString()
if observation type in field 3 is character
For each observation, repeat the fields in the previous table.
Note: If observations are larger than 32K, then they might span multiple physical messages.

Data Set Index - "ATI"

If the data set index message is needed, the data set index message is sent following the data set observations message. This message type is recognized by the "ATI" field name in all fields.
The following table shows the layout of the index definition.
Note: All character strings are null terminated.
Fields for the Data Set Index
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
type of record is index = 4
2
int
tibrvMsg_AddI32()
number of records in this message
3
long
tibrvMsg_AddI32()
upercmx
4
long
tibrvMsg_AddI32()
length of index or key name
5
char[]
tibrvMsg_AddString()
index or key name
6
long
tibrvMsg_AddI32()
flags
7
long
tibrvMsg_AddI32()
number of variables in the index or key
8
long
tibrvMsg_AddI32()
number of keys
9
char[]
tibrvMsg_AddString()
key name
For each key, repeat field 9 in the previous table. For each record, repeat fields 3-9 in the previous table.

Data Set Integrity Constraints - "ATC"

If the data set integrity constraints message is needed, then the data set integrity constraints message is sent following the data set index message. This message type is recognized by the "ATC" field name in all fields.
The following table shows the layout of the integrity constraints definition.
Note: All character strings are null terminated.
Fields for the Data Set Integrity Constraints
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
type of record is integrity constraint = 5
2
int
tibrvMsg_AddI32()
number of records in this message
3
long
tibrvMsg_AddI32()
IC type
Based on the value of field 3 in the previous table, use the following tables.
  • If the field type is CHECK for field 3, then use the fields in the following table. For each buffer, repeat field 11 in the previous table, incrementing the field ID each time.
    Fields for the CHECK Field Type
    Field ID
    Field Type
    Function
    Description
    4
    long
    tibrvMsg_AddI32()
    max length for this IC
    5
    char[]
    tibrvMsg_AddString()
    name of IC
    6
    long
    tibrvMsg_AddI32()
    retval
    7
    long
    tibrvMsg_AddI32()
    total length
    8
    char[]
    tibrvMsg_AddString()
    list of wtnames
    9
    long
    tibrvMsg_AddI32()
    whlen
    10
    long
    tibrvMsg_AddI32()
    number of members in tree
    11
    byte[]
    tibrvMsg_AddOpaque()
    whbuf buffer
  • If the field type is not CHECK for field 3, then use the fields in the following table.
    Fields for Field Types Other than CHECK
    Field ID
    Field Type
    Function
    Description
    4
    long
    tibrvMsg_AddI32()
    max length for this IC
    5
    char[]
    tibrvMsg_AddString()
    name of IC
    6
    long
    tibrvMsg_AddI32()
    nvar - number of variables
    7
    long
    tibrvMsg_AddI32()
    number of NNAME records
    8
    char[]
    tibrvMsg_AddString()
    NNAME
    For each NNAME value, repeat field 8 in the previous table, incrementing the field ID each time. Subsequent field IDs will increase from here.
  • If the field type is not CHECK or FOREIGN KEY for field 3, then use the following table for field 9.
    Fields for Field Types Other than CHECK or FOREIGN KEY
    Field ID
    Field Type
    Function
    Description
    9
    long
    tibrvMsg_AddI32()
    filler value = 1
  • If the field type is not CHECK but it is FOREIGN KEY for field 3, then use the fields in the following table.
    Fields for the FOREIGN KEY Field Type
    Field ID
    Field Type
    Function
    Description
    9
    long
    tibrvMsg_AddI32()
    total length of following fields
    10
    long
    tibrvMsg_AddI32()
    fkdelt
    11
    long
    tibrvMsg_AddI32()
    fkupd
    12
    long
    tibrvMsg_AddI32()
    pklng + 1
    13
    char[]
    tibrvMsg_AddString()
    pkname
    14
    char[8]
    tibrvMsg_AddString()
    pkfname libref
    15
    long
    tibrvMsg_AddI32()
    length of member name
    16
    char[]
    tibrvMsg_AddString()
    member name.
    17
    long
    tibrvMsg_AddI32()
    ICP attributes
For each record in the message, repeat field 3 and all subsequent fields in the previous tables.

External File Descriptor - "FDC"

This message type is recognized by the "FDC" field name in all fields. For each "FDC" record, send either a text file or a binary file. You can send more than one file in an attachment but the files must be either all text files or all binary files. Each file must have an "FDC" message and then one of the following:
  • one or more "ATX" messages for the text files
  • one or more "ATB" messages for the binary files
The following table shows the layout of the external file descriptor.
Fields for the External File Descriptor
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
size of logical record
2
int
tibrvMsg_AddI32()
file size

Text File Attachment - "ATX"

This message type is recognized by the "ATX" field name in all fields.
The following table shows the layout of the text file attachment body.
Fields for the Text File Attachment
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
number of records in this message
2
long
tibrvMsg_AddI32()
length of data in field 3
3
char[]
tibrvMsg_AddString
file data
For each record in the message, repeat fields 2 and 3.

Binary File Attachment - "ATB"

This message type is recognized by the "ATB" field name in all fields.
The following table shows the layout of the binary file attachment body.
Fields for the Binary File Attachment
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
number of records in this message
2
long
tibrvMsg_AddI32()
length of data in field 3
3
tibrv_u8
tibrvMsg_AddOpaque
file data
For each record in the message, repeat fields 2 and 3.

Last Message of Attachment - "LST"

All attachments must end with an "LST" message. This message type is recognized by the "LST" field name in all fields. This message type contains a count of the number of messages sent for the attachment, not including itself.
The following table shows the layout of the last message.
Fields for the Last Message
Field ID
Field Type
Function
Description
1
int
tibrvMsg_AddI32()
number of messages sent for attachment