Using the Command Argment Buffer, anArgBuffer[ ]

anArgbuffer is the 32-bit integer array that holds the pointers to command arguments. Its size is defined in pixcl.h and in PiXCL 10.2 is set to 64 which is large enough to handle alll existing commands.

When a command ARGLIST is parsed by the ParseArgList function, argument type pointers are assigned from index [0]. Except for strings, there is one entry for each argument.

For static strings, e.g. "some string value" , two buffer entries are required. The first is an LPSTR pointer to the start of the string, and second is the length of the string including the terminating NULL character.

For a string variable e.g. SomeString$ , a single entry is a pointer to a STRVARRECORD structure.

Command descriptions in Proc* functions

The coding style in all the Proc* functions lists the anArgBuffer entries in a comment block. This is done as a check against the ARGLIST content in text.cpp and also to define what each argument is supposed to be, within the function code.

For example, the DrawMirrorText command included this comment block with the function code.

anArgBuffer[0,1] = x,y

anArgBuffer[2,3] = text$, length

anArgBuffer[4,5,6] = RGB colour

anArgBuffer[7] = mirror gap (pixels)

anArgBuffer[8] = mirror percentage

Interpret* functions are similar. Let's look at the DebugMsgBox command that supports two syntax versions:

DebugMsgBox(string$|integer|float&|integer64#|double#&) and

DebugMsgBox(string$|integer|float&|integer64#|double#&, suffix$)

There are three ARGLIST structures for this.

ARGLIST alDebugMsgBox1 [ ] = {

P_BRACKET_LEFT,'\0',

P_VARIANT,'\0',

// Note NO delimiter.

P_END

};

ARGLIST alDebugMsgBox2 [ ] = {

P_BRACKET_RIGHT,'\0',

P_END

};

ARGLIST alDebugMsgBox3 [ ] = {

P_DELIMITER,'\0',

P_STRING,'\0',

P_BRACKET_RIGHT,'\0',

P_END

};

It's important to note here that an attempt to parse each ARGLIST is made, in order. If the Parse operation is successful, the arg buffer is updated starting from index 0. Hence, for alDebugMsgBox1 which always parses successfully,

anArgBuffer[0] = pointer to the variable

anArgBuffer[1] = string length for strings only, otherwise the content is not defined, and is usually 0.

When alDebugMsgBox3 is parsed, we get

anArgBuffer[0] = LPSTR pointer to the start of the string

anArgBuffer[1] = string length

Note here that the indices restart from 0. This means that the first anArgBuffer[0] pointer to the variable to be displayed has been overwritten, and so this pointer will have to be saved before alDebugMsgBox3 is parsed. This can be seen in the InterpretDebugMsgBox function code in geopxl01.cpp .

A common programming error when interpretting variable commands that use the P_VARIANT element type that includes strings and numeric types is to not take into account the string length entry in anArgBuffer.