Message Formats
Following is a brief description of the basic format for data sent to and from Connect. Syntax for each command is explained briefly. Syntax specifies the order in which you must generate a Connect command as well as any parameters and switches associated with the command.
Input Command Format to Connect
Single commands sent to Connect use the following format:
<CommandName> <ObjectPath> [<CommandData>]
Although the <CommandName> field isn't case sensitive, the <ObjectPath> is. <CommandData> may or may not be case sensitive.
where:
| Syntax | Description |
|---|---|
<CommandName> | The name of a particular command (e.g., Load). |
<ObjectPath> | The STK instance (e.g., Scenario/stkDemo/Satellite/Shuttle) to which the <CommandName> directs action. |
[<CommandData>] | <CommandData> fields modify a <CommandName> and may or may not be required. Please refer to the format of the individual commands for additional information. |
Multiple commands can be sent to Connect in one transaction by separating them with semicolons (;).
Since only one scenario can be open at any given time in STK, you can substitute the scenario name with a wildcard (*) so that the <ObjectPath> is Scenario/* or just *. For example, you could type Scenario/* for Scenario/stkDemo, where * refers to the scenario loaded.
Output Message Format from Connect
Messages sent from Connect can be received in several formats, including a simple acknowledgment, a single message, multiple messages and asynchronous messages which can be single or multiple message formats.
The AgConnect library hides this implementation from a remote application with the AgConnect C API
Acknowledge Message Format
When the acknowledge feature is ON and the command sent was successfully processed by STK, Connect sends an acknowledgment message (received as "ACK") in response to the receipt of an incoming command.
If an error occurs while processing the input command, Connect sends a not acknowledged message (received as "NACK") to the originator of the command. If a Connect command is issued that should return data but instead
returns a NACK message, the command failed and no data will follow.
Single Message Format
Single message responses returned by Connect to an application use the following format:
<Header> <Data>
where:
| Syntax | Description |
|---|---|
<Header> | A fixed-length, 40-byte packet containing the <CommandName> (all
upper case) followed by an integer number specifying the length of any data
following. |
<Data> | The actual data being returned by Connect. |
For example, in response to a GetDB / command, Connect returns a message similar to:
ACK
GETDB·23·
/net/doc/sheila/stkData
where ACK is the acknowledgment message, GETDB 23 is the <Header> (boxes
indicate blank spaces), and <Data> is /net/doc/sheila/stkData.
Multiple Message Format
Multiple messages returned by Connect to an application use the following format:
<MultMessageHeader> <MultipleMessageData> <SingleMessageHeader> <SingleMessageData>...
where:
| Syntax | Description |
|---|---|
<MultMessageHeader> | A fixed-length, 40-byte packet containing the <CommandName> (all
upper case) followed by an integer number specifying the length of the multiple
message data. |
<MultipleMessageData> | Contains the number of single messages to follow. |
<SingleMessageHeader> | Contains the <CommandName> (all upper case) followed by an integer
number specifying the length of the data following. Multiple message format
contains any number of single message headers depending on the command entered. |
<SingleMessageData> | Data for the preceding message header. |
For example, in response to a GetAccesses / command, Connect returns a message similar to:
Sample return message with multiple message header and data
ACK
GETACCESSES 3
73
GETACCESSES 111 /Application/STK/Scenario/stkDemo/Facility/Perth /Application/STK/Scenario/stkDemo/Facility/Baikonur NoAccesses
GETACCESSES 114 /Application/STK/Scenario/stkDemo/Facility/Santiago /Application/STK/Scenario/stkDemo/Facility/Baikonur NoAccesses GETACCESSES 111
/Application/STK/Scenario/stkDemo/Facility/Santiago /Application/STK/Scenario/stkDemo/Facility/ Perth NoAccesses
GETACCESSES 113
/Application/STK/Scenario/stkDemo/Facility/Wallops /Application/STK/Scenario/stkDemo/Facility/Baikonur NoAccesses
.
.
.
GETACCESSES 170 /Application/STK/Scenario/stkDemo/Satellite/ERS1
/Application/STK/Scenario/stkDemo/Facility/Wallops/Sensor/FiveDegElev 1 Nov 2000 00:33:06.88 1 Nov 2000 00:45:05.96
Asynchronous Message Format
If the asynchronous feature is ON and Asynchronous Mode is commanded by the remote application, a return message in asynchronous format is sent. The format for an asynchronous message is as follows:
| Field Name | Type | Length (Bytes) | Value | Comments |
|---|---|---|---|---|
| Sync Pattern | Characters | 3 | "AGI" | |
| Header Length | Char-Digits | 2 | 42 | |
| Header Version | Char-Digits | 1 | 1 | |
| Revision | Char-Digits | 1 | 0 | |
| Type Length | Char-Digits | 2 | ||
| Async Type | Characters | 15 | ||
| Identifier | Characters | 6 | ||
| Total Packets | Char-Digits | 4 | One relative | |
| Packet Number | Char-Digits | 4 | One relative | |
| Data Length | Char-Digits | 4 | Can be 0 when no data is associated with the packet |
Asynchronous Mode means that responses and data may be returned in an order that corresponds to the completion of the requested operations, therefore, the return in format is not necessarily synchronous order. For example, you might send two operations which we'll call Operation One (1) and Operation Two (2). If Operation Two (2) completes before Operation One (1), it will also return its data before Operation One (1). Application coding must account for this possibility.