|
Application Messaging
Attachment Layout for TIB/Rendezvous
An attachment is
comprised 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.
| 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 contained in a message type, then the
message is not required to be sent. The
following table shows the field name, purpose of each
message type, and the order in which messages
should be sent for a data set.
| 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 file(s)
- one or more "ATB" messages for the binary file(s)
The
following table shows the field name, purpose of each
message type, and the order in which messages
should be sent for an external file.
| 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 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.
| 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 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.
| 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 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 ID's.
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.
| 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.
| 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.
| 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, variable messages may 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.
| 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, they may 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.
| 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/key name |
| 5 |
char[] |
tibrvMsg_AddString() |
index/key name |
| 6 |
long |
tibrvMsg_AddI32() |
flags |
| 7 |
long |
tibrvMsg_AddI32() |
number of variables in the index/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, 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.
| 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 one of the following tables
-
If the field type is CHECK for field 3, then use the fields in the following table.
| 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 |
For each buffer, repeat field 11 in the previous table,
incrementing the field ID each time.
If the field type is not CHECK for field 3, then use the
fields in the following table.
| 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 ID's will increase
from here.
Based on the value of field 3 in the first table of this section, use one of the following tables:
If the field type is not CHECK or FOREIGN KEY for field 3,
then use the following table for field 9.
| 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.
| 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 file(s)
- one or more "ATB" messages for the binary file(s)
The following table shows the layout of 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.
| 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.
| 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.
| Field ID |
Field Type |
Function |
Description |
| 1 |
int |
tibrvMsg_AddI32() |
number of messages sent for
attachment |
|
