12.5.1 Command List Construction

As mentioned previously, the command list and its contents are represented in different, but complementary, ways by the SP-ICE-3 ClientLib and on the SP-ICE-3 Card:

Client-CommandLists may be instantiated by an application program as required by the program's logic.
Card-CommandLists, however, cannot be instantiated directly by an application: instead, they will by instantiated automatically on the card as and when necessary.

Client-CommandList

A new Client-CommandList can be constructed in the normal way:

Pseudo-code only - do not copy!

Copy

using ( ClientAPI client = new ClientAPI( myCardIP ) )
{

CommandList localList = new CommandList();

# etc.

}

After this, you can add contents to it as appropriate for your application.

Please also take careful note of the information in 12.6.3 Recommended Maximum CommandList Size.

Card-CommandList

The contents of a new Card-CommandList

will be created automatically, along with the Card-CommandList instance itself, when ListAPI.Set( id, myContents ) is called, with a suitable Client-CommandList being passed as the contents provider myContents.

The contents of an existing Card-CommandList

can be extended by calling ListAPI.Set( id, moreContents, true ), with a suitable Client-CommandList being passed as the additional contents provider moreContents.
can be replaced by calling ListAPI.Set( id, otherContents, false ), with a suitable Client-CommandList being passed as the replacement contents provider otherContents.
may be deleted by calling ListAPI.Delete( id ), as long as ListAPI.Status( id ) != Processing.
may be altered (extended, replaced) as long as ListAPI.Status( id ) != Processing.
can be retrieved for inspection by calling ListAPI.Get( id ), which returns a new Client-CommandList.

Example of contents construction

A short CommandList could be defined, very roughly, as follows:

Pseudo-code only - do not copy!

Copy

using ( ClientAPI client = new ClientAPI( myCardIP ) )
{
double maxX = 32760;
double minX = -32760;
double maxY = 32760;
double minY = -32760;

int remoteListID = 1;

CommandList localList = new CommandList();

localList.AppendJumpSpeed( 1.0 );
localList.AppendMarkSpeed( 0.1 );
localList.AppendJumpAbs( minX, minY );
localList.AppendMarkAbs( maxX, minY );
localList.AppendMarkAbs( maxX, maxY );
localList.AppendMarkAbs( minX, maxY );
localList.AppendMarkAbs( minX, minY );
localList.AppendJumpAbs( 0, 0 );

// 
// display the LOCAL list contents:
// 
Console.WriteLine("LOC: " + localList.ToString());

// 
// send contents to a remote list on the card:
// 
client.List.Set( remoteListID, localList);

// 
// retrieve and display the REMOTE list contents:
// 
Console.WriteLine("REM: " + client.List.Get(remoteListID).ToString());

}

The console output should be similar to this:

Copy

LOC: JS 1;MS 0.1;JA -32760 -32760;MA 32760 -32760;MA 32760 32760;MA -32760 32760;MA -32760 -32760;JA 0 0;
REM: JS 1;MS 0.1;JA -32760 -32760;MA 32760 -32760;MA 32760 32760;MA -32760 32760;MA -32760 -32760;JA 0 0;

Note
Each CommandCode is represented by its CommandCodeAcronym.