API - Routines available at Clisitef
In this chapter, we will present the functions available in clisitef. For Therefore, the following conventions will be adopted:
Empty field or not provided -- in the standard version it is a field containing just the delimiter (binary zero). In the ASCII version, if it is a field fixed it contains spaces. If it is a variable field it only contains the start and end field delimiter.
Field size -- in the case of a fixed size field, when this value is provided, indicates the minimum size to be reserved by the application to receive a response from SiTef.
Type of function parameters -- we will divide into two groups:
1. Regarding the flow of information: the parameter can be input or output.
2. When passing: the parameter can be passed by value or by reference.
Each routine described in this chapter typically has two versions/interfaces:
Standard interface -- traditional, allows parameters with data binaries
ASCII Interface -- for interfacing with programming languages, whose parameters work only in ASCII.
What differentiates the ASCII version from the standard version is the addition of the suffix A in the name of the functions, and the way/type of passing the parameters.
Standard interface#
This interface can be used by applications written in most variable programming languages that accept binary fields. Among We mention: Delphi, Visual Basic, Visual C.
In the case of receipts, the character 0x0a (\n in C language) indicates the end of a line.
All routines called by the automation application must be of type stdcall, i.e., the parameters are stacked from right to left left and the called routine is responsible for removing them from the stack. A Parameter convention is as follows:
Table 1: Parameter types and convention#
| Type | Description |
|---|---|
| char * | ASCII text buffer terminated by binary zero. |
| short int (short), unsigned short int (ushort) | Variables that occupy 2 bytes in memory, with and without sign, respectively. |
| int, unsigned int (uint) | Variables that occupy 4 bytes in memory, with and without sign, respectively. |
| void | Indicates the absence of parameters or return. |
| <variable type> * (example: short int * or int *) | Indicates that the "variable type" variable is being passed as an address, that is, CliSiTef will use the automation application area to work, and may return some results there. |
ASCII Interface#
This interface can be used by applications written in any programming language, including those that do not accept fields binaries, such as Oracle's Forms environment.
In it all parameters are passed in ASCII and can be of size fixed and variable.
Numeric fields are always passed with a fixed size and aligned to right, with zeros on the left. In particular, the field whose content is a negative value, has a "-" sign in the leftmost position of the number (e.g.: -0001 for a 5-position field whose content is the value --1).
Variable length ones are constructed so that the first character indicate which value was chosen to be the delimiter of that field or That is, the field is delimited by the chosen character or its complementary in the case of the pairs "( )", "[ ]", "{ }" and "< >".
Examples of valid constructions are:
(1234), \[1234\], {1234}, <1234\>, \$1234\$, %1234%, \|1234\|, etc.
NOT VALID examples are as follows:
$12$34$, .1.234,56., etc.
The criterion for choosing the delimiter must be that it does not exist as a valid character in the field in question. In data passes from application for CliSiTef, as they are always known, the application can define a default character and always use it in all data passes. In the return, as any character is valid (for example on a receipt), the above rule must be used in interpretation of the result returned by CliSiTef since this will choose the character that best adapts to the answer that is being generated.
Finally, there is a special character that is used in texts directed to a printer. The "\" (backslash) indicates the end of one line and must be used by the application to instruct the printer to close the current line and position yourself in the next one.