Alterando bits individuais de um tag com a função SetBit.

1. Introdução

É comum precisar ligar ou desligar um único bit de um tag inteiro, por exemplo acionar o bit 0 de uma word de comando sem alterar os demais bits. O E3Globals oferece a função SetBit justamente para isso.

Um erro frequente é chamar SetBit sobre o valor do tag e esperar que a alteração seja aplicada automaticamente:

'NÃO funciona: o retorno é descartado
SetBit Application.GetObject("Driver.Tag1").Value, 0, False

Nesse formato, o bit é calculado, mas nada é escrito no tag. Isso acontece porque SetBit não altera o valor no local: ela retorna o valor já modificado. A correção é reatribuir esse retorno ao tag.

2. O que são SetBit e GetBit

Ambas são funções do E3Globals, disponíveis tanto em scripts quanto em associações.

Função	Assinatura	Retorno
SetBit	`SetBit(Value, BitIndex, BitValue)`	Inteiro com sinal de 32 bits (o valor de `Value` com o bit alterado)
GetBit	`GetBit(Value, BitIndex)`	Booleano (`True`/`False`) do bit indicado

Parâmetros de SetBit:

Value: inteiro sem sinal de 32 bits. Se um valor de ponto flutuante for informado, apenas a parte inteira é utilizada.
BitIndex: posição do bit, de 0 a 31. Valores fora dessa faixa geram erro.
BitValue: booleano (True ou False) a atribuir ao bit.

3. Por que a alteração não tem efeito

SetBit é uma função pura: ela recebe um número, calcula um novo número com o bit ajustado e devolve esse resultado. Ela não modifica a variável passada como Value nem escreve diretamente no tag.

Quando se escreve apenas SetBit(Tag.Value, 0, False), o novo valor é produzido e imediatamente descartado, e o tag continua com o valor antigo. A solução é fechar o ciclo ler, modificar e escrever em uma única atribuição: reatribuir o retorno de SetBit ao Value do tag.

Por que isso resolve o problema?

Ao atribuir o retorno de SetBit de volta a Tag.Value, o E3 grava o novo inteiro no tag. É essa gravação que efetiva a alteração do bit.

4. Como usar

Por script

Para atribuir o valor False ao bit 0 de um tag:

' Seta o valor FALSE no bit 0 do tag
Application.GetObject("Driver.Tag1").Value = _
SetBit(Application.GetObject("Driver.Tag1").Value, 0, False)

Para ligar o mesmo bit, basta trocar o último parâmetro para True:

'Seta o valor TRUE no bit 0 do tag
Application.GetObject("Driver.Tag1").Value = _
SetBit(Application.GetObject("Driver.Tag1").Value, 0, True)

Para ler o estado de um bit (por exemplo, o bit 3):

'Retorna True ou False conforme o bit 3 do tag
Dim bEstado
bEstado = GetBit(Application.GetObject("Driver.Tag1").Value, 3)

Em uma associação

Como SetBit/GetBit também funcionam em associações, é possível, por exemplo, associar uma propriedade de um objeto de tela ao estado de um bit com GetBit(Tag.Value, n).

5. Resultado

Forma de uso	Comportamento
Retorno descartado `SetBit(Tag.Value, 0, False)`	O bit é calculado, mas o tag não muda.
Retorno reatribuído `Tag.Value = SetBit(Tag.Value, 0, False)`	O tag recebe o novo inteiro e a alteração do bit é efetivada.

6. Observações e boas práticas

Reatribua sempre o retorno. SetBit nunca altera o valor no local. O resultado precisa ser gravado de volta no tag (ou em outra variável) para ter efeito.
Gravação do inteiro completo. A atribuição grava no tag o inteiro completo de 32 bits, não apenas o bit alterado. Se outra origem também escreve nesse tag, avalie a concorrência de escrita para não sobrescrever valores.
Faixa do índice. BitIndex deve estar entre 0 e 31. Fora disso, ocorre erro.
Valores fracionários. Se Value for de ponto flutuante, apenas a parte inteira é considerada.
Retorno com sinal. SetBit retorna um inteiro com sinal de 32 bits. Para bits altos, o número resultante pode aparecer negativo, mas o padrão de bits gravado é o correto.
Leitura com GetBit. Para testar um bit sem alterá-lo, use GetBit, que retorna diretamente True/False.