User function parameters

Input parameters

The calling state table passes input parameters to a user function. Input parameters are restricted to the following data types:

char

A single character or a character string.

Character strings are denoted by type char followed by length X, where X is the maximum length of the string including the NULL terminator. When character strings are returned, the string must be truncated to the length of the data including the NULL character. For examples of how to code this type of parameter, see Functions 1, 2, 3, and 4 in Example user function parameters.

uchar

An unformatted binary string.

Note: A uchar of length 1 is implemented as a uchar[1], whereas a char of length 1 is implemented as a single character.

short

A short integer (2 bytes). For examples of how to code this type of parameter, see Function 1, and Function 2.

long

A long integer (4 bytes). For examples of how to code this type of parameter, see Functions 3, 5, 6, 7, 8, 9, and 10 in Example user function parameters.

struct

The beginning of the definition of variables within a structure. Structures can be nested. For examples of how to code this type of parameter, see Function 9, and Function 10.

endstruct

The end of the data variables within the structure.

output pointer

A pointer to a buffer for output parameters. For examples of how to code this type of parameter, see Functions 4, 5, 6, and 7 in Example user function parameters.

Output parameters

A user function passes output parameters back to the calling state table. Output parameters are restricted to the following data types:

char

A single character or a character string. For examples of how to code this type of parameter, see Functions 3, 6, 7, and 10 in Example user function parameters.

Character strings are denoted by type char followed by length X, where X is the maximum length of the string including the NULL terminator. When character strings are returned, the string must be truncated to the length of the data including the NULL character.

short

A short integer (2 bytes). For examples of how to code this type of parameter, see Functions 4, 7, and 8 in Example user function parameters.

long

A long integer (4 bytes). For examples of how to code this type of parameter, see Functions 2, 3, 5, 7, and 10 in Example user function parameters.

struct

The beginning of the definition of variables within a structure. For an example of how to code this type of parameter, see Function 9.

endstruct

The end of the data variables within the structure.

You can define one or more output parameters for a user function in the User Function window.

If there is only one output parameter the user function can use the C return statement, to reply to the calling state table. For examples, see Function 1 and Function 2.

If there is more than one output parameter you have two options:

1. Define an OUTPTR in the Input Parameters pane of the User Function window. For examples, see Functions 4, 5, 6, and 7 in Example user function parameters.
2. If an OUTPTR is not defined as above a system generated main expects the user function to return a pointer to a buffer containing the data. For examples, see Functions 3, 8, 9, and 10 in Example user function parameters.

   Note that example Function 8 has only one output parameter, but it has a Return Type Multiple and therefore must return the address of a buffer containing successive values of the single output parameter. This is discussed below in Multiple instances of output parameters.

Passing output parameters using the output pointer

Output parameters can be returned indirectly from the user function by reserving one of the input parameters to contain the address of the output parameter. In this case, the user functions must be defined as int and return an int return code to indicate whether or not the execution was successful. For example, in the following function call, the return_code indicates whether execution of the function was successful or not, and the value of the output parameter is stored in output:

return_code = function_name(input1,input2,&output)

A system-generated main() function expects the value of return_code to be 0 if execution is successful, or -1 if it failed.

The output pointer variable can be the address of single parameters, multiple output parameters, or groups of single or multiple output parameters. For code examples see Functions 4, 5, 6, and 7 in Example user function parameters.

Multiple instances of output parameters

A user function can return multiple instances (an array) of the output parameters. In this case, you must allocate a buffer of contiguous memory. The buffer must be declared so that the data is persistent in the main function until the call to the CA_Put_DT_Parameters() subroutine.

For example, you might return a list of names that match a search string: this would be multiple instances of one char parameter (for a code example see also Function 8). To indicate the number of instances, the first four bytes of the buffer must be a long integer (for a code examples see Functions 9 and 10 in Example user function parameters) containing the number of instances being returned (the “name count” shown in Figure 1 and the “order count” shown in Figure 2).

To indicate that the user function can return multiple instances select the Return Type Multiple on the User Function window.

The state table can issue ReceiveData once per instance of the output parameters, stopping at count times.

Figure 1. Multiple instances of one output parameter

Figure 2. Multiple instances of more than one output parameter

Passing output parameters back to the state table

When you define a user function you can identify those output parameters that are to be “ignored” by the calling state table (see 11). This does not affect the way the user function is written, but will determine which parameters are passed to the calling state table. In the state table, the ReceiveData action simply makes no mention of the ignored parameter.