Previous Page | Next Page

Using the SAS Common Messaging Interface

Attachment Layout for TIB/Rendezvous

Overview of Attachment Layout for TIB/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.  [cautionend]

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:

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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.  [cautionend]

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/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, 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.  [cautionend]

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.

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:

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

Previous Page | Next Page | Top of Page

Copyright © 2010 by SAS Institute Inc., Cary, NC, USA. All rights reserved.