API - Rotinas disponíveis na CliSiTef

Neste capítulo, apresentaremos as funções disponíveis na clisitef. Para tanto, serão adotadas as seguintes convenções:

Campo vazio ou não fornecido -- na versão padrão é um campo contendo apenas o delimitador (zero binário). Na versão ASCII, se for um campo fixo ele contém espaços. Se for um campo variável ele contém apenas o delimitador de início e final de campo.

Tamanho do campo -- no caso de campo de tamanho fixo, quando esse valor for fornecido, indica qual o tamanho mínimo a ser reservado pela aplicação para receber uma resposta do SiTef.

Tipo de parâmetros da função -- dividiremos em dois grupos:

1. Quanto ao fluxo de informações: o parâmetro pode ser de entrada ou saída.

2. Quando à passagem: o parâmetro pode ser passado por valor ou por referência.

Cada rotina descrita neste capítulo, normalmente, possui duas versões/interfaces:

Interface padrão -- tradicional, permite parâmetros com dados binários

Interface ASCII -- para interface com linguagens de programação, cujos parâmetros trabalham somente em ASCII.

O que diferencia a versão ASCII da versão padrão é o acréscimo do sufixo A no nome das funções, e a forma / tipo de passagem dos parâmetros.

Interface padrão

Esta interface pode ser utilizada por aplicações escritas nas mais variáveis linguagens de programação que aceitam campos binários. Dentre elas citamos: Delphi, Visual Basic, Visual C.

No caso de comprovantes, o caractere 0x0a (\n em linguagem C) indica o final de uma linha.

Todas as rotinas chamadas pelo aplicativo de automação devem ser do tipo stdcall, ou seja, os parâmetros são empilhados da direita para a esquerda e a rotina chamada é responsável por removê-los da pilha. A convenção dos parâmetros é a seguinte:

Tabela 1: Tipos e convenção de parâmetros

Tipo	Descrição
char *	Buffer em texto ASCII terminado por zero binário.
short int (short), unsigned short int (ushort)	Variáveis que ocupam 2 bytes em memória, com e sem sinal, respectivamente.
int, unsigned int (uint)	Variáveis que ocupam 4 bytes em memória, com e sem sinal, respectivamente.
void	Indica a ausência de parâmetros ou retorno.
<tipo variável> * (exemplo: short int * ou int *)	Indica que a variável do "tipo variável" está sendo passada como endereço, ou seja, a CliSiTef irá utilizar a área da aplicação de automação para trabalhar, podendo devolver algum resultado nela.

Interface ASCII

Esta interface pode ser utilizada por aplicações escritas em qualquer linguagem de programação, inclusive as que não que aceitam campos binários, tais como o ambiente Forms da Oracle.

Nela todos os parâmetros são passados em ASCII e podem ser de tamanho fixo e variável.

Os campos numéricos são passados sempre com tamanho fixo e alinhados a direita, com zeros a esquerda. Em particular, o campo cujo conteúdo seja um valor negativo, possui um sinal "-" na posição mais a esquerda do número (p/ex: -0001 para um campo de 5 posições cujo conteúdo é o valor --1).

Os de tamanho variável são construídos de forma que o primeiro caractere indique qual o valor escolhido para ser o delimitador daquele campo ou seja, o campo é delimitado pelo caractere escolhido ou o seu complementar no caso dos pares "( )", "[ ]", "{ }" e "< >".

Exemplos de construções válidas são:

(1234), \[1234\], {1234}, <1234\>, \$1234\$, %1234%, \|1234\|, etc.

Exemplos NÃO VÁLIDOS são os seguintes:

$12$34$, .1.234,56., etc.

O critério para escolha do delimitador deve ser o de que ele não exista como caractere válido no campo em questão. Nas passagens de dados da aplicação para a CliSiTef, como estes sempre são conhecidos, a aplicação pode definir um caractere padrão e sempre utilizá-lo em todas as passagens de dados. Já no retorno, como qualquer caractere é valido (por exemplo em um comprovante), a regra acima deve ser utilizada na interpretação do resultado devolvido pela CliSiTef uma vez que esta irá escolher o caractere que melhor se adapta a resposta que está sendo gerada.

Finalizando, existe um caractere especial que é utilizado nos textos direcionados para uma impressora. O "\" (barra reversa) indica o final de uma linha e deve ser utilizado pelo aplicativo instruir a impressora para fechar a linha corrente e se posicionar na seguinte.