lotus script

1 – CONCEITOS GERAIS

• Workflow: software para controlar os passos necessários para completar toda uma atividade.

• Workgroup: grupo de pessoas que compartilham arquivos, dados e possivelmente aplicações. Os softwares de workgroup são projetados para permitir interações colaborativas.

• Groupware: software baseado em tecnologia Client/Server, permitindo vários usuários compartilharem uma área comum de informações.

Exemplos de ferramentas groupware:Lotus Notes® – LOTUSExchange – MICROSOFT

Group Wise – NOVELL

1.1 - LOTUS NOTES®

É um ambiente de computação para grupo de trabalho que ajuda as pessoas a trabalharem em conjunto de uma maneira mais eficiente. Com ele, as pessoas podem trabalhar juntas, independente da plataforma ou dos limites geográficos, técnicos ou organizacionais. As informações baseadas no Notes® podem ser compartilhadas a qualquer distância e a qualquer momento. O Notes® é uma ferramenta de comunicação, para suprir a necessidade de automatizar o ambiente de trabalho fazendo com que os documentos fluam normalmente, seguindo um fluxo lógico de acompanhamento a eles.

MODO INTELIGENTE DE SE COMUNICAR, COOPERAR E COORDENAR

1.2 - SERVIDORES DO NOTES® E ESTAÇÕES DE TRABALHO

O Notes® consiste em dois programas principais: Servidor e Estação de Trabalho.

O Servidor do Notes®: Um computador que executa o OS/2, Windows/NT ou UNIX - fornece serviços a usuários da estação de trabalho do Notes® e a outros servidores do Notes®, inclusive armazenamento de bancos de dados compartilhados e transferência de mensagens.

A Estação de Trabalho do Notes®: Um computador que executa o software do sistema Windows/NT, OS/2, Macintosh ou UNIX - comunica-se com os servidores do Notes®, de modo que você possa usar os bancos de dados compartilhados e ler e enviar mensagens.

1.3 – USUÁRIOS NOTES®

Administradores: Gerenciam os usuários, as redes e os bancos de dados do Notes® para assegurar que todos estejam acessando corretamente os bancos de dados.

Designers: Criam e modificam os bancos de dados (aplicativos) para que os usuários possam compartilhar informações de maneira eficaz.

Usuários: Criam, editam e compartilham documentos com outros usuários do Notes®.

CAPÍTULO 1 – LOTUS SCRIPT BÁSICO

• LotusScript Básico

LotusScript é uma linguagem de programação que estende as capacidades de desenvolvimento de aplicações da Lotus, particularmente, Lotus Notes. LotusScript se assemelha a Visual Basic (VB) e se você está familiarizado com VB, então aprender LotusScript é fácil.

• Sintaxe usada no LotusScript

Variáveis do LotusScript, tipos de dados, estrutura de dados estrutura, operadores, funções e subs, laços e condicionais, cadeia de caracteres, funções de data/hora, arquivos,... são cobertos.

Neste capítulo você irá aprender sobre o LotusScript, a linguagem de programação usada nos produtos da Lotus. O capítulo abrange LotusScript básico e sua sintaxe e estrutura. O que você aprender neste capítulo pode ser usado em qualquer produto Lotus que use o LotusScript.

Este Capítulo já assume que você não é leigo em programação e que já tenha alguma experiência com linguagens como Visual Basic e outras.

1 O Quê é LotusScript ?

LotusScript é uma linguagem de script básica. Ela primeiramente apareceu no Lotus Improv, um produto inovador que foi desenvolvido para Windows em 1992. Gradualmente, mais produtos Lotus incorporaram o LotusScript, incluindo Formulários Notes e Lotus Notes Vip ( que foi vendido posteriormente para Revelation ).

Neste Capítulo, nós investigaremos os elementos da Linguagem LotusScript de uma forma prática. Serão usados exemplos para facilitar o aprendizado. Nós começaremos com “ Como adicionar comentários ao seu código”.

2 Adicionando Comentários ao seu Código

O primeiro e mais importante assunto para aprender em uma linguagem de programação é a maneira de acrescentar comentários ao seu código.

As linhas de comentários iniciam com apóstrofo. De fato, qualquer coisa após um apóstrofo é considerado como um comentário e você pode facilmente adicionar comentários no final da linha. Você também pode usar %REM and %END REM para blocos de linhas de comentários como mostra o exemplo:

‘ Uma linha simples de comentário . . .

‘ . . . e outra

%REMA primeira linha de um comentário com múltiplas linhas

A última linha de um comentário com múltiplas linhas

%END REM

DICA

É importante que você use comentários em suas linhas de programação para facilitar a manutenção do programa por você e também por uma outra pessoa que venha a assumir suas tarefas.

3 Entendendo as Variáveis do LotusScript

No LotusScript, como em qualquer linguagem de programação, as variáveis são usadas para armazenar e manipular dados. Existem algumas regras que devem ser seguidas quando da nomeação das variáveis no LotusScript:

• O primeiro caracter deve ser uma letra;

• Os demais caracteres podem ser letras, números,...;

• Os nomes das variáveis podem ter no máximo 40 caracteres;

• Não existe distinção entre nomes maiúsculos e minúsculos.

Estas regras básicas são aplicadas também a nome de constantes, tipos, classes, funções, procedimentos, subrotinas e propriedades.

4 Constantes no LotusScript

Muitas constantes são criadas para tornar seu programa mais fácil. A tabela 1.0 abaixo mostra estas constantes.

Tabela 1.1 Constantes do LotusScript

Constantes

Descrição

FALSE O valor boleano é falso. Representada por 0TRUE O valor boleano é verdadeiro. Representado por -1.NULL Para variáveis do tipo variante, indica que a variável não tem valorNOTHING Para variáveis que podem se referenciar a um objeto, indica que a

variável não está se referenciando a um objetoPI Do termo matemático π =~ 3,14

Algumas constantes programadas são definidas em arquivos especiais que você pode incluir em seus scripts. Estes arquivos são conhecidos como “include files” e têm a extensão .LSS que significa “LotusScript Source file “. Use a diretiva %INCLUDE na sessão de declaração para incluir o arquivo .LSS. Veja o exemplo abaixo:

%INCLUDE “ LSCONST.LSS ”

Estas constantes tornam seu programa mais legível. Por exemplo, MB_OK e MB_OKCANCEL podem ser usados na função MsgBox.

DICA

Quando o Notes é instalado na forma padrão, todos os arquivos .LSS são armazenados no diretório de programas do Notes. Para saber mais sobre estes arquivos e suas constantes, veja-os em um editor de texto como o Bloco de Notas.

Você pode definir suas próprias constantes usando a declaração de constantes. É uma maneira para tornar seu código mais legível. Por exemplo, para definir constantes que definam tamanhos de produtos, você pode definir o fragmento de código seguinte:

Const SIZE_SMALL = 1

Const SIZE_MEDIUM = 2

Const SIZE_LARGE = 3

Por conversão, todos os nome de constantes são capitalizados.

5 Entendendo Tipos de Dados

Todas as variáveis no LotusScript têm um tipo associado a elas. Este tipo define, basicamente, duas coisas:

• Quanto de espaço deve ser reservado para os dados que estão armazenados nas variáveis;

• Que tipo de expressões podem usar as variáveis.

Para esclarecer melhor, uma vez declarada a variável do tipo inteira, o LotusScript reserva dois bytes para o seu valor ser armazenado na variável e verifica que a variável só pode ser usada em expressões para valores inteiros.

LotusScript suporta os tipos de dados na tabela 2.0 abaixo:

Table 1.2 Tipos de Dados do LotusScript

Tipo de Dado Número de Bytes Armazenados Sufixos

Integer 1 %Long 4 &Single 4 !Double 8 #Currency 8 @String 2 por caracter $Variant 16 Nenhum

6. Declarando Variáveis

Não é necessário declarar uma variável porque na primeira vez que você usa uma nova variável, LotusScript declara ela para você automaticamente como uma variável do tipo Variant.

DICA

Sempre declare as variáveis na sessão de declaração geral. Isto força a declaração de todas as variáveis que você usa e ajuda você quando da depuração do programa

Você declara as variáveis usando a expressão Dim. Por exemplo, o fragmento de código seguinte declara três variáveis: iCont como inteiro, strName como string e curPrice como currency:

Dim iCount As Integer

Dim strName As String

Dim curPrice As Currency

Você pode adiciona qualquer dos sufixos mostrados na tabela 2.0 para declarar as variáveis. Veja o exemplo abaixo:

Dim sRatio!

Dim dLimit#

DICA

Não é bom usar sufixos quando declara variáveis. Isto torna seu código mais difícil de entender por alguém que não sabe que, por exemplo, ! quer dizer uma variável single.

Se não é explicitado o tipo da variável, é atribuído a ela o tipo Variant. As duas linhas abaixo declaram variáveis com Variant:

Dim varFontTipe As Variant

Dim varFontName

DICA

É bom que o programador pratique todos os tipos de variáveis quando possível. Isto tira qualquer dúvida sobre o tipo de variável que você deve usar e faz seu código mais fácil de sofrer manutenção.

Veja que o prefixo que adotamos faz parte do nome da variável. Apesar dele não ser necessário, ele ajuda a você checar que você está usando a variável correta na expressão. Por exemplo, só em olhar o nome das variáveis no seu código, você estará constatando se as variáveis usadas na expressão são do mesmo tipo.

Os prefixos são variados entre os diversos programadores. A tabela 1.3 mostra exemplos de prefixos.

Tabela 1.3 Sugestões de Prefixos para Nomes de Variáveis

Data Type Prefix Example

Integer I IDocsDeletedLong L LFilesLengthSingle S SWeightCoefficientDouble D DAccelerationCurrence Cur CurSalaryIncreaseString Str StrDocTitleVariant Var VarName

7 Convertendo Tipos de Dados

Em muitos casos, quando você atribui dado de um tipo para uma variável de um tipo diferente, LotusScript automaticamente converte o dado para você. LotusScript converte dados de tipos diferentes usando a sequência de tipos seguintes: Integer, Long, Single, Double e Currency.

Se você usar variáveis do tipo long e do tipo single em uma mesma expressão, LotusScript converte o valor long em um valor single antes de prosseguir na expressão.

LotusScript possui um conjunto de funções que convertem variáveis em diferentes tipos. As funções são listadas na tabela 1.4 e permite a você:

• Converter dados de um tipo para outro;

• Converter números em cadeias;• Converter cadeias em números;

• Checar o tipo de dado de uma variável.

Tabela 1.4 Funções de Conversões de Dados

Funções Descrição

Bin$ Converte o número fornecido em uma String que representa seu valor binário

Ccur Converte o valor fornecido em CurrencyCDat Converte o valor fornecido em Variant do tipo dataCDbl Converte o valor fornecido em DoubleCInt Converte o valor fornecido em IntegerCLng Converte o valor fornecido em LongCSng Converte o valor fornecido em SingleCStr Converte o valor fornecido em StringDataType Retorna um valor Integer que representa o tipo de dado do valor fornecidoHex$ Converte o número em uma String que representa seu valor hexadecimalOct$ Converte o número em uma String que representa seu valor octal.Str$ Converte um número em uma String.TypeName Retorna uma String que representa o tipo de dado do valor fornecidoVal Converte a String fornecida em um número do tipo Double.

7.1 Convertendo Dados de um Tipo para Outro

Use CCur, CDat, CDbl, CInt, CLng, CSng e CStr para converter dados de um tipo para outro. Geralmente, você faz conversões de tipos para Ter certeza que o resultado de

um cálculo é de um certo tipo. Por exemplo, o fragmento de código seguinte mostra como ter certeza que o preço calculado retorna um valor do tipo Currency:

Dim iQuantidade As Integer

Dim curPreco As Currency

Dim curTotal As Currency

CurTotal=CCur(iQuantidade + curPreco)

7.2 Convertendo um Número em uma Cadeia de Caracteres

O LotusScript tem funções que convertem números em cadeias. Str$ converte o valor numérico dado em cadeia, acrescentando um espaço no início se o número for positivo. Se você não quer espaços, use a função CStr O exemplo seguinte imprime “ 143”:

Print Str$(143)

As funções Bin$, Hex$ e Oct$ convertem os números fornecidos em cadeias que contêm a representação binária, hexadecimal e octal de cada um respectivamente. O exemplo seguinte imprimi “101”:

Print Bin$(5)

7.3 Convertendo Cadeia de Caracteres em Número

Use a função Val para converter uma cadeia em um número. A função Val retorna um valor Double contendo a representação numérica da cadeia.

7.4 Checando o Tipo de Dado de uma Variável

Existem duas funções que checam o tipo de dado de uma variável: DataType e TypeName. DataType retorna um integer representando o tipo de dado da variável ou expressão sendo checada. O arquivo LSCONST.LSS contem um conjunto de constantes pré-declaradas que você pode usar para interpretar o valor retornado por DataType. TypeName é semelhante a DataType exceto que ao invés de retornar um inteiro, ele retorna uma String descrevendo o tipo de dados. Veja o exemplo seguinte:

Dim strNome As String

Print TypeName(StrNome)

8 Estrutura de Dados do LotusScript

LotusScript suporta estrutura de dados comuns de arrays e listas. Ele também suporta estruturas de dados orientadas a objeto; por exemplo, você pode criar suas classes, métodos e propriedades. Você também pode usar LotusScript para trabalhar com objetos OLE e ActiveX.

8.1 Arrays

No LotusScript, você pode declarar dois tipos de arrays, estáticas e dinâmicas. Uma array estática é uma array de tamanho fixo, contento um número fixo de elementos. Você pode criar e deletar elementos. Uma array dinâmica pode ser redimensionada a qualquer hora; você pode torná-la maior e menor adicionando e removendo elementos. Veja a tabela 1.5 com as funções que você pode usar para trabalhar com arrays.

Tabela 1.5 Funções de Arrays

Comandos ou Funções Descrição

Dim Declara uma array estática e inicializa seus elementosErase Inicializa cada elemento de uma array fixa. Para arrays

dinâmicas, deleta todos seus elementosIsArray Dado uma variável ou expressão, Retorna verdadeiro se uma

expressão for uma arrayLbound Retorna o menor índice de uma arrayReDim Declara uma array dinâmica e aloca espaço para seus

elementos ou modifica o tamanho de uma array dinâmica existente

Ubound Retorna o maior índice de uma array

Você declara uma array estática usando o comando Dim. Você especifica o seguinte:

• O número de dimensão para array;

• O limite ( dimensão ) da array;

• O tipo de dado a ser armazenado.

Dim aloca espaço para a array e automaticamente inicializa cada elemento com um valor padrão. Até que você especifique outro, o primeiro elemento de uma array tem o índice 0. Se preciso, você pode mudar seu padrão para 1, usando a expressão “Ooption base 1”. As declarações abaixo declaram variáveis estáticas:

Dim strNome(9) As String ‘ Declara 10 elementos com índices de 0 a 9

Dim iMatriz(9,9) As Integer ‘ Declara 100 elementos

Dim iVetor(1 to 50) As Integer ‘Declara 50 elementos com índices de 1 a 50

Você também pode usar Dim para declarar arrays dinâmicas. Porém, quando você declarar uma array dinâmica usando Dim, especifique apenas o tipo. Você não especifica o número de elementos da array e não é alocado espaço para a array. Antes de usar uma array dinâmica, você tem que usar o comando ReDim para alocar algum espaço para seus elementos. Por exemplo, o código abaixo mostra como declarar uma array dinâmica e alocar agum espaço para ela:

Dim iElemento As Integer ‘ Declara o número de elementos a ser usado

Dim strVetor() As String ‘ Declara a array dinâmica

IElemento = 25

ReDim strVetor(iElemento) ‘ Aloca para este número de elementos

Você pode também declarar e inicializar uma array usando ReDim. Por exemplo, para declarar uma array contento seis elementos do tipo Integer e inicializar cada elemento com 0, use o seguinte código:

Option Base 1 ‘ Especifica que o primeiro elemento de qualquer array tem o índice 1

ReDim var Peso(6) As Integer ‘ Declara uma array dinâmica com elementos cujos

índices vão de 1 a 6.

Você pode usar ReDim para redimensionar uma array dinâmica com a opção de preservar o conteúdo da array ou reinicializando seus elementos. Por exemplo, se você tem uma array dinâmica, iVetor, contendo 50 elementos e você precisa aumentar seu tamanho para 100 elementos preservando seu conteúdo corrente, use o seguinte código:

ReDim Preserve iVetor(99)

Se você precisa achar o tamanho de uma array dinâmica em tempo de execução, você pode usar as funções LBound e UBound. Use essas funções com o nome de uma array e opcionalmente com seu tamanho. LBound retorna o menor índice da array e UBound o maior. Por exemplo, após redimensionar iVetor, Lbound(iVetor) é 0 e UnBound(iVetor) é 99.

Você pode usar o comando Erase para deletar todos os elementos de uma array dinâmica e liberar o espaço usado pela array. Em uma array estática, você pode usar Erase para reinicializar cada elemento.

Você pode atribuir uma array a uma variável do tipo Variant. Consequentemente, você pode checar se uma variável contem uma array usando a função IsArray. Se a variável ou expressão fornecida é uma array, a função retorna verdadeiro. Por exemplo:

Dim var Icons As Variant

Dim lIconsIDs(255) As Long

Print IsArray(varIcons) ‘ False

VarIcons = lIconIDs

Print IsArray(varIcons) ‘ True

8.2 Listas

Uma lista é similar a uma array e contém um conjunto de elementos. Ela diferencia de uma array quando da identificação e uso de seus elementos. Com arrays, você identifica seus elementos usando índices. Com lista, você identifica elementos usando uma string. Veja a tabela 1.6 que exibe as funções usas com listas:

Tabela 1.6 Funções de Lista

Comandos e Funções

Descrição

Dim Declara a listaErase Para a lista, remove todos os seus elementos. Para elementos da

lista, remove o elemento da listaForAll Laço entre os elementos da listaIsElement Dado o nome da lista e a string, retorna verdadeiro se a string é

um elemento da listaIsList Verifica se a variável é uma listaLisTag Pode ser apenas usada dentro de um bloco ForAll e retorna o

nome do elemento da lista

Use Dim para declarar uma lista vazia como se segue:

Dim curAmountOutstanding List As String

Quando você declara uma lista, ela não possui elemento e não é alocado espaço para ela. Você adiciona elementos a lista adicionando novas strings. Por exemplo, você pode criar dois elementos na lista, cujas strings são ABC e XYZ, usando o código abaixo:

CurAmountOutstanding(“ABC”) = 12.99

CurAmountOutstdanding(“XYZ”) = 52.00

Você usa a string para se referenciar a um elemento da lista da mesma forma que você usa um índice para ser referenciar a um elemento de uma array. Por exemplo, para somar esses dois elementos que acabamos de criar, veja o código abaixo:

Dim curTotal as Currency

CurTotal = CurAmountOutstanding(“ABC”) + CurAmountOutstanding(“XYZ”)

Use Erase para deletar elementos específicos de uma lista, ou todos os elementos. Por exemplo:

Erase CurAmountOutstanding(“ABC”) ‘ Remove o elemento da lista

Erase CurAmountOutstanding ‘ Remove todos os elementos da lista

Caso você queira checar se foi adicionado um elemento a uma lista, usando a função IsElement. Forneça a string do elemento procurado e a função retorna verdadeiro se o elemento fizer parte da lista. For example:

IsElement(curAmountOutstanding(“XYZ”))

Você também pode checar se uma variável é uma lista. Por exemplo:

IsList(curAmountOutstanding)

Para percorrer os elementos de uma array, você tipicamente usa um loop para percorrer todos os índices da array. No caso de uma lista, você usa um ForAll loop junto com a função ListTag. Por exemplo:

ForAll varElement In curAmountOutstanding Print ListaTag(varElement) ; “ owes “ ; varElement

End ForAll

Há pontos importantes que devem ser anotados quando se uma ForAll. No exemplo acima, a variável “varElement” é um tipo especial de variável usada pelo LotusScript quando executando loops ForAll. No corpo do loop, cada elemento da lista é atribuido a variável de referência. Você nunca tem que declarar uma variável de referência; LotusScript declara todas as variáveis de referência como variant por você . Se você tentar declarar uma variável de referência, aparecerá erro de compilação.

Dentro de um loop ForAll, você pode usar função ListTag para achar a string correspondente ao elemento corrente. Esta função só é usada dentro de um loop ForAll.

CUIDADO

LotusScript suporta somente arrays e listas com um tamanho máxio de 64k. Tome cuidado com esse limite quando alocar arrays e listas grandes.

8.3 Tipos Definidos pelo Usuário

Você pode definir suas próprias estruturas de dados usando a expressão type. Basta fornecer o novo nome do tipo e definir uma ou mais variáveis membro para o tipo.

NOTA

O termo variável membro é usado para referenciar qualquer variável incluída em uma definição de tipo de usuário.

Por exemplo, para declarar um novo tipo com três variáveis membros, você poderia usar a declaração de tipo seguinte:

Type Custumer

LCustID As Long

StrCusFirstName As String

StrCusSurname As String

CurBalance As Currency

End Type

Você pode então declarar novas variáveis deste tipo; por exemplo:

Dim custNew As Customer

Dim custMailing As List Customer

Dim custMostFrequentBuyers(99) As Customer

Você se referencia a uma variável membro usando a forma VarNome.MembroNome onde VarNome é o nome da variável do tipo definido pelo usuário e MembroNome é o nome da variável membro.

CustNew.lCustID = 14829

CustNew.strCustFirstName = “ Chris “

CustNew.curBalance = 100.00

8.4 Classes e Objetos Definidos pelo Usuário

Você pode definir suas próprias classes e objetos com LotusScript. A declaração de classe é semelhante a declaração de tipo, exceto que além de variáveis membros você pode definir também procedimentos membros. Você pode definir dois procedimentos especiais com classes: New e Delete. New é usado para definir variáveis membros para um objeto de uma classe. Delete é definido se você precisa fazer qualquer processo especial quando um objeto de uma classe é deletada. O exemplo seguinte mostra uma classe simples com 4 variáveis membro e quatro procedimentos membros:

Class custObject

LcustID As Long ‘ variável membro

StrCustFirstName As String

StrCustSurName As String

CurBalance as Currency

Sub New(Lid As Long, strFirstName As String, strSurname As String, curBal As Currency) ‘ Define o construtor

lCustID = lID

strCustFirstName = strFirstName

strCustSurName = strSurName

curBalance = curBal

End Sub

Sub Delete ‘ Define o destrutor

Print “ Customer “ ; strCustfirstName ; “ “ ; strCustSurName ; “ deleted. “ End Sub

Sub SetBalance(curBal As Currency)

CurBalance = curBal

End Sub

Function curQueryBalance As Currecy

CurQueryBalance = curBalance

End Function

End Class

Você usa Dim para declarar variáveis objeto. Quando você usa Dim com um nome de uma classe, você está declarando uma referência a um objeto. Então, use New para criar um novo objeto e Set para atribuir o objeto à variável referenciada. Por exemplo:

Dim custNew As custObject

Set custNew = New custObject(14829, “ Chris “, “ Edwards “, 100.00)

Por default, a variável membro criada é privada para a classe enquanto a função membro é pública. Isto é, você não pode se referenciar diretamente a uma variável membro, mas a uma função você pode. Por exemplo:

CustNew.SetBalance(50.00) ‘ Certo

CustNew.curBalance = 50.00 ‘ Errado

CurCurrentBalance = custNew.curQueryblance ‘ Certo

CurCurrentBalance = custNew.curBalance ‘ Errado

O comando With permite um meio diferente de acessar procedimentos públicos e variáveis membros de um objeto. Por Exemplo:

With custNew

Call .SetBAlance(50.00)

CurCurrentBalance = .curQueryBalance

End With

Você pode deletar um objeto usando a função Delete como mostrado:

Delete custNew

Se você tem definido uma subrotina Delete na sua classe, ela é executada antes do objeto ser excluído.

Por exemplo, quando você exclui o objeto no seu exemplo, a subrotina Delete mostra “ Customer Chris Edwards deleted “. Veja a tabela 1.7 que exibe comandos e funções que são usadas com classes e objetos.

Tabela 1.7 Funções e Comandos de Classes e Objetos

Comandos e Funções Descrição

Class Usado para declarar uma classe de objeto definido pelo usuárioDelete Executa a subrotina Delete para objetos definidos pelo usuárioIsObject Retorna verdadeiro se a expressão fornecida for um objetoNew Usado para criar um novo objeto definido pelo usuárioSet Associa um objeto a uma variávelWith Usado para acessar procedimentos públicos e variáveis de objeto

8.5 Objetos OLE e ActiveX

Você pode acessar as classes, métodos, e propriedades de objetos OLE e ActiveX usando LotusScript e Notes. Isto quer dizer que você pode usar Notes para transferir dados de aplicativos como Microsoft Excel and Lotus WordPro, então trabalhar com os dados usando classes de objetos da aplicação. Você também pode programar objetos ActiveX como Lotus Components diretamente do LotusScript. A tabela 1.8 exibe comandos e funções para objetos OLE e ActiveX.

Tabela 1.8 Funções e comandos de objetos OLE e ActiveX

Comandos e Funções Descrição

CreateObject Dado o nome de uma classe de objeto OLE, Cria um objeto OLEGetObject Dado o caminho de uma arquivo e o nome de uma classe OLE,

abre um objeto OLE a partir de um arquivoIsObject Retorna verdadeiro se a expressão fornecida for um objetoSet Associa um objeto a uma variável

Você pode criar um novo objeto OLE ou ActiveX usando a função CreatObject. Basta fornecer o nome da classe do objeto que você quer criar e o LotusScript cria o objeto. Se necessário, LotusScript iniciará a aplicação requerida para criar o objeto. O exemplo seguinte mostra como criar um nove documento WordPro e salvá-lo:

Dim objDoc As Variant

Set objDoc = CreateObject( “ WordPro.Application”)

ObjDoc.NewDocument “ “, “ “, “C:\Docs\EBS.MWP”, “ “ “ “ “ “

‘ Atualizando o documento aqui . . .

objDoc.SaveAs “C:\Docs\REPORT.LWP”, “ “, “ “, False, True, False

Call objDoc.Close(False)

Para abrir um objeto existente, use GetObject. Você fornece o caminho do arquivo contento o objeto e opcionalmente o nome da classe. LotusScript acha e abre o objeto. O exemplo seguinte mostra como abrir um objeto WordPro:

Dim objDoc As Variant

‘ Abre um documento WordPro

Set objDoc = GetObject(“C:\DOCS\REPORT.LWP”)

9 Entendendo Operadores LotusScript

No LotusScript, os operadores são usados para realizar os seguintes tipos de funções:

• Aritmético;

• Lógico;

• Comparação;

• Concatenação.

Tabela 1.9 Operadores Aritméticos

Operador Descrição Exemplo Resultado

- Número negativo -34 -34 - Subtrai dois números 7 – 5 2 + Adiciona dois números 5 + 9 14* Multiplica dois números 7 * 6 42/ Divide dois números 16 / 5 3.5\ Divisão de inteiros 16 \ 5 3Mod Resto de uma divisão inteira 16 Mod 5 1 ^ Potência de um número 5 ^ 2 25

Tabela 1.10 Operadores de Comparação


= Retorna verdadeiro se dois valores são iguais 5 = 6 False <> >< Retorna verdadeiro se dois valores não são iguais 5 <> 6 True < Retorna verdadeiro se um valor é menor que o

outro7 < 9 True

> Retorna verdadeiro se um valor é maior que o outro 7 > 9 False >= => Retorna verdadeiro se um valor é maior ou igual a

outro8 >=8 True

<= =< Retorna verdadeiro se um valor é menor ou igual a outro

8 <= 8 True

Is Retorna verdadeiro se dois objetos referenciam-se para o mesmo objeto

ObjA Is ObjB

True/False

Tabela 1.11 Operadores Lógicos


Not Negação lógica Not B Verdadeiro se B é falso; Falso do contrário And And lógico A And B Verdadeiro se A e B verdadeiros; Falso do

contrárioOr Or lógico A Or B Verdadeiro se A ou B verdadeiros; Falso do

contrárioXor Or exclusivo A Xor B Verdadeiro se apenas um verdadeiro; Falso

se A e B falsos ou verdadeirosEqv Equivalência

lógicaA Eqv B Verdadeiro se A e B são falsos ou

verdadeiros; Falso do contrárioImp Implicação lógica A Imp B Verdadeiro se A falso ou ambos são

verdadeiros; Falso se A verdadeiro e B falso

Tabela 1.12 Operadores de Strings


& Concatena duas strings “AB”+”CD” “ABCD”

+ Concatena duas strings “AB”+ “CD” “ABCD”

Like Retonra verdadeiro se uma string combina com outra string fornecida

“ABC” Like “A*” True

10 Usando Funções e Subs

No LotusScript, você pode definir funções e subs que serão chamadas para realizar funções específicas. Por exemplo, você pode definir uma função que converte uma data com dois dígitos de ano para uma data com quatro dígitos. A principal diferença entre uma função e uma sub é que a primeira retorna um valor e a segunda não.

10.1 Declarando funções e subs

Você declara uma função usando a palavra-chave function como se segue:

Function fIsWeekend(iDay As Integer) As Integer

Você dá um nome a função, define a lista de argumentos que serão passados e finalmente define o tipo de valor que será retornado. Para retornar um valor, atribua este valor ao nome da função como é mostrado no exemplo seguinte:

Function fIsWeekend(varDate As Variant) As Integer

If Weekday(varDate) = 1 Or Weekday(varDate) = 7 then

fIsWeekend = TrueElse

fIsWeekend = false

End If

End Function

Para definir subs não é preciso declarar um tipo de retorno. Uma declaração de sub típica é mostrada abaixo:

Sub GoToBeach(strResort As String, iMilesToResort As Integer)

10.2 Chamando funções e subs

Para chamar uma função basta atribuí-la a uma variável. Por exemplo:

Dim fGoToWork As Integer

Dim varToday As Variant

VarToday = Today ‘ A função “ today ” retorna a data de hoje

FGoToWork = fIsWeekend(varToday)

Para chamar uma sub você pode usar um dos seguintes métodos:

Call SubName(Arg1, Arg2, ...)

Call SubName Arg1, Arg2

SubName(Arg1, Arg2, ....)

Por exemplo:

If fISWeekend(varToday) then

Call GotoBeach(“ Maui “, 4000)

End If

Quando você passa valores a subs e funções, você precisa saber das duas seguintes maneiras que o LotusScript pode passar argumentos:

• Por referência: LotusScript passa uma referência do argumento. A função trabalha com o argumento. Qualquer mudança feita no argumento reflete no original;

• Por valor: LotusScript passa uma copia do argumento para a função. A função trabalha com a copia. Qualquer mudança na copia não afeta o original.

Alguns argumentos, como arrays, listas e objetos são sempre passados por referência. Se você sempre quer um argumento passado por valor, use a palavra-chave ByVal quando você declara o argumento na declaração de uma função ou sub. No exemplo seguinte, o segundo argumento é passado por valor:

Sub DeleteDocument(iDocNumber As Integer, ByVal strDocTitle As String)

11 Loop e Branch

LotusScript proporciona uma variação de caminhos para controlar o fluxo de execução de um código. Você pode usar loops para executar repetidamente um conjunto de expressões (comandos) a partir de uma certa condição. Você pode usar branches para executar partes diferentes de um código baseado nos resultados de comparações ou no valor de variáveis.

11.1 For...Next Loops

Você usa For...Next loop para executar um conjunto de expressões um certo número de vezes. Você especifica:

• Uma variável de controle do loop;

• Um valor inicial para a variável;

• Um valor final para a variável;

• Um valor de passo que será adicionado a variável depois de cada execução do loop. Se não especificado, o padrão é 1.

A primeira vez que o loop é executado, a variável de controle tem o valor inicial. Depois de cada execução, a variável de controle é atualizada adicionando o valor de passosa variável. Se você usa um valor de passo positivo, o loop acaba quando a variável de controle é maior ou igual ao valor final. Por exemplo:


For iCount = 1 To 10 Step 2

‘ Faz alguma coisa

Next

Neste exemplo, o loop é executado 5 vezes com iCount tendo os valores 1, 3, 5, 7 e 9.

11.2 ForAll Loops

Nós já tivemos um primeiro contato com este tipo de loop quando falamos do uso de listas no LotusScript. Porém, você não usa ForAll loops apenas com listas. Por exemplo, você pode usá-lo para percorrer todas as visões de um banco de dados Notes:

Dim session As New NotesSession

Dim db As NotesDatabase

Set db = session.CurrentDatabase

ForAll varView In db.Views

‘ Faz alguma coisa

End ForAll

11.3 Do...While Loops

Use este tipo de loop para executar um bloco de expressões repetidamente enquanto uma condição especial é verdadeira. Antes do loop ser executado, a condição é testada. Se for verdadeira, o bloco é executado então. Se a condição for falsa, o loop não

será executado e o controle é passado para a próxima expressão ou comando depois do loop. Por exemplo, o loop seguinte é executado três vezes e mostra 17, 18 e 19:


Dim iMax As Integer

iMax = 20

iCount = 17

Do While iCOunt < iMax

Print iCount

iCount = iCount + 1

Loop

Uma alternativa para o loop acima é testar a condição depois do loop ser executado. Aqui, o loop é executado pelo menos uma vez. Por exemplo:


Dim iMax As Integer

iMax = 20

iCount = 17

Do Print iCount

iCount = iCount + 1

Loop While iCOunt < iMax

11.4 Do...Until Loops

Com este tipo de loop, o conjunto de expressões dentro dele é executado até que sua condição seja verdadeira. Veja o exemplo:


Dim iMax As Integer

iMax = 20

iCount = 17

Do Until iCount < iMax

Print iCount

iCount = iCount + 1

Loop

Neste exemplo o loop nunca será executado porque a condição é verdadeira antes de entrar no loop. A condição pode ser executada depois do loop ser executado. Aqui, o loop também é executado pelo menos uma vez. Por exemplo:


Dim iMax As Integer

iMax = 20

iCount = 17

Do Print iCount

iCount = iCount + 1

Loop Until iCount < iMax

11.5 If...Then...Else branches

Você pode usar If...Then...Else para selecionar qual expressão ou comando que é executado a partir de uma condição específica. Se a condição for verdadeira, um conjunto de expressões é executada; se a condição for falsa, um conjunto diferente é executado. Por exemplo:

If iCount > iMax Then

Print “ Muitos itens “

Else

Print iCount; “ iten(s) “

End If

Você pode omitir a parte Else da expressão se você quer somente 6executar um conjunto de expressões quando uma condição é verdadeira. Por exemplo:

If iDaysOverdue > 14

Print “ Tempo de comprar mais peças “

End If

11.6 Select...Case branches

Esta expressão deixa você selecionar um bloco de expressões para executar baseado no valor de uma expressão. Por exemplo:

Select Case iBoxesOrdered

Case Is <= 0 : Call ProcessInvalidOrder(iBoxesOrdered)

Case 1 : ProcessSmallOrder(iBoxesOrdered)

Case 2 to 15 : Call ProcessMediumOrder(iBoxesOrdered)

Case 16 to 31 : Call ProcessLargeOrder(iBoxesOrdered)

Case Else : Call ProcessHugeOrder(iBoxesOrdered)

End Select

11.7 GoSub and On...GoSub

Com uma sub ou uma função, você pode usar GoSub and On...GoSub para desviar para uma label específica no procedimento. Uma label é simplismente uma maneira de identificar um lugar no seu código. O código na label pode executar um comando de retorno para a expressão seguinte ao GoSub. Por exemplo, o código seguinte desvia para label lblLogError se a quantidade do pedio for negativa:

Sub ProcessInvalidOrder(iOrderQuantity As Integer)

If iOrderQuantity < 0 Then

GoSub lblLOgErrorEnd If

Exit Sub

lblLogError:

Call LogError

Return

End Sub

Você pode usar On...GoSub para desviar para uma label de um conjunto de labels a partir de um valor fornecido. Veja o exemplo:

On iErrorNumber GoSub lblA, lblB, lblC

Se iErrorNumber é 1, o programa desvia para lblA; se iErrorNumber é 2, o programa desvia para lblB; se iErrorNumber é 3, o programa desvia para lblC. Se iErrorNumber é 0 ou maior que 3, a expressão On...GoSub é ignorada.

A desvantagem de usar o comando GoTo(On...GoTo) ao invés de GoSub(On...GoSub) é que naquele não podemos usar o comando return.

12 Trabalhando com Strings

LotusSript tem uma grande quantidade de funções que você pode usar para manipular string. Nesta sessão nós veremos:

• Criação de SubStrings;

• Formatando Strings;

• Achando e comparando Strings.

A tabela 1.13 exibe uma lista de comandos e funções que você pode usar.

Tabela 1.13 Funções e Comandos para String

Funções e Comandos

Descrição

Asc Dado uma string, retorna o código de caracter da stringChr Dado um código de caracter, retorna o caracter correspondente ao códigoFormat Formata uma string de acordo com o tipo de formato especificadoInStr Dado duas strings, retorna a posição do caracter(InStr) onde uma string

ocorre primeiro em outra.Lcase Converte os caracteres de uma string em minúsculosLeft Dado uma string e um número n, retorna n caracteres mais a esquerda da

stringLen Retorna o número de caracteres de uma stringLset Adiciona uma string A a outra B onde A é truncada se for maior que B ou é

preenchido com espaços a direita quando A menor que B.Ltrim Remove os espaços excedentes a esquerda de uma stringMid Retorna uma substring de uma string dado o início e o fim da substringRight Dado uma string e um número n, retorna n caracteres mais a direita da

stringRset Adiciona uma string em uma outra alinhada a direita. Se a primeira for

maior que a Segunda, é colocado espaços adicionais no seu lado esquerdo. Do contrário, só os elementos mais a esquerda da substring permanecem na string

Rtrim Remove os espaços em brancos a direita de uma stringSpace Adiciona n espaços a um stringStrCompare Compara duas strings de acordo com o método de comparaçãoTrim Remove espaços a direta e a esquerda de uma stringUcase Converte os caracteres de uma string em maiúsculosUchr Retorna o caracter correspondente a um número no código UnicodeUni Dado uma string, retorna o código de caracter Unicode, para o primeiro

caracter na stringUstring Dado uma dimensão e também um código, Unicode ou um caracter,

retorna uma string dos caracteres especificados do tamanho fornecido

12.1 Criando strings

Você usa Dim para declarar variáveis do tipo string. O tamanho de uma string pode ser fixo ou variado. Veja o exemplo:

Dim strVariableLength As String

Dim strFixedLength As String * 20

Como declarado, strFixedLength contem 20 caracteres. Se você quer alterar uma string para um tamanho particular após ela ser declarada, você pode usar a função Space$ para atribuir a string um número específico de espaços. Por exemplo:


StrName = Space$(32)

De forma alternativa, você pode usar a função String$ para atribuir a string qualquer número de um caracter específico, código ASCII e UniCode.

Strname = String$(32, “ x ” )

NOTA

A função Asc retorna o código de caracter ASCII correspondente ao caracter fornecido. Da mesma forma, a função Uni retorna o código de caracter Unicode de um caracter. Se você realmente sabe o código apropriado, você pode usar o caracter correspondente usando Chr para ASCII e Uchr para código Unicode.

12.2 Criando substrings

A partir de uma string você pode usar tipos diferentes de funções para criar substrings. Com as funções Left e Left$, você pode substrings consistindo de um número específico de caracteres iniciando a esquerda da string. O exemplo seguinte mostra como:


Dim strFirstName As String

StrName = “ John G Testar “

StrFirstname = Left$(strName, 4) ‘ O strFirstName passa a ser John

Da mesma forma, você pode usar as funções Right e Right$ para extrair caracters do lado direito da string. Por exemplo:

StrSurname = Right$(strName, 6) ‘ O strSurName passa a ser Testar

Use as funções Mid e Mid$ para extrair caracteres de qualquer parte da string. Você fornece a posição inicial e o número de caracteres como mostrado:

StrMiddleInitial = Mid$(strName, 6, 1) ‘ O strMiddleInitial passa a ser G

Para achar o tamanho de uma string, você pode usar a função Len. Por exemplo:

Dim iLength As Integer

ILength = Len(strName) ‘ A variável recebe o valor 13

NOTA

Muitas funções LotusScript têm duas versões, uma que termina com $ e outra que não termina com $. Se você usa a primeira versão, o tipo de dado de retorno é String. Se você usa a segunda versão, o tipo de dado de retorno é Variant.

Você pode remover espaços em branco de uma string usando Trim, LTrim, e RTrim. Como seus nomes sugerem, Trim remove espaços a esqueda e direita de uma string, LTrim remove espaços a esquerda da string e RTrim remove espaços a direita da string.

CUIDADO

Muitas funções de string tem uma versão que trabalha com caracteres, tal como Left, e outra que trabalha com bytes, tal como LeftB. Isto é bom quando um caracter é armazenado em um byte. Porém, por causa do método de codificação UniCode usado pelo LotusScript representar cada caracter por dois bytes de código de caracter, você dever estar precavido ao usar as funções de string orientadas a bytes como LeftB, LenB, MidB e RightB. Elas podem dar resultados inesperados com strings Unicode. Use Left, Mid e Right ao invés delas.

12.3 Formatando strings

Você pode mudar os caracteres de uma string para minúsculo usando a função Lcase ou para maiúsculo usando a função Ucase. Para formatos mais avançados use a função Format. Você pode usar esta função para formatar string, data/tempo ou números de acordo com uma string. Se você quer ter certeza que strings estão corretamente alinhadas, use as funções LSet ( alinhamento a esquerda ) e RSet ( alinhamento a direita ). Por Exemplo:

Dim strLabel As String

StrLabel = Space$(8)

LSet strLabel = “ABC” ‘ Atribui a strLabel “ABC “ porque o tamanho corrente da

variável é 8.

RSet strLabel = “XYZ” ‘ Atribui XYZ a variável

StrLabel = “ABC”

12.4 Encontrando e comparando strings

Se você precisa encontrar uma string dentro de outra string, você pode usar a função Instr para achar a posição do primeiro caracter da string procurada, fornecendo o seguinte:

• A posição inicial onde será feito a busca na string. O padrão é o início da string;

• A string a ser verificada;

• A string a ser procurada;

• Um número para indicar se a procura faz distinção entre caracteres maiúsculos e minúsculos ou não.

Você pode comparar duas strings usando a função strCompare. Para usuá-la basta fornecer o seguinte:

• As duas strings a serem comparadas;

• Um número para identificar o tipo de comparação.

A função retorna:

• -1 se a primeira string é menor que a segunda;

• 0 se as strings são iguais;

• 1 se a primeira string for maior que a Segunda.

13 Manipulação de Datas e Horas

As funções LotusScript que você pode usar para manipular datas e horas são mostradas na tabela 1.14

Tabela 1.14 Funções de manipulação de datas e horas


Descrição

Date Retorna a data e hora corrente do sistema ou altera a mesmaDateNumber Dado um ano, mês e dia do mês, retorma o valor data/hora

correspondenteDateValue Dado uma string representando uma data, retorna um um valor data/hora

correspondenteDay Dado um valor data/hora, retorna o dia do mêsHour Dado um valor data/hora, retorna a horaIsDate Retorna verdadeiro se uma expressão dada representa uma dataMinute Dado um valor data/hora, renorta os minutosMonth Dado um valor data/hora, renorta o mêsNow Retorna a data corrente do sistema como um valor data/horaSecond Dado um valor data/hora, renorta os segundosTime Retorna o hora de sistema corrente como um valor data/horaTimeNumber Dado uma hora, minuto e segundo, retorna o valor data/hora

correspondenteTimer Retorna o número de segundos que tenham decorrido desde meia-noiteTimeValue Dado uma string representando uma hora, retorna o valor data/hora

correspondenteToday O mesmo da função DateWeekday Dado um valor data/hora, retorna um número representando um dia da

semanaYear Dado uma valor data/hora, retorna o ano.

Veja os exemplos:

Print DateNumber(1992, 5, 29) ‘ Exibe 5/29/92

Print DateValue(“May 29, 1992”) ‘ Exibe 5/29/1992

Print DateNumber(1992-2,5-3,29-12) ‘ Exibe 2/17/90

Print TimeNumber(20,40,3) ‘ Exibe 8:40:3 PM

PrintTimeValue(“20:40”) ‘ Exibe 8:40 PM

DICA

Você pode usar a Função Timer para cronometrar partes de seu programa. Por exemplo, para checar quanto tempo é necessário para ler um arquivo grande de um servidor de arquivo, chame a função Timer antes e depois de ler o arquivo e subtraia os dois valores.

Uma vez tendo um valor data/hora, você pode usar Year, Day, Hour, Minute e Segundos para extrair suas partes. Você usa a função WeekDay para retornar um número que representa o dia da semana.

14 Trabalhando com Arquivos

Há muitas maneiras de trabalhar com arquivos usando LotusScript. A tabela 1.15 mostra as funções disponíveis.

Tabela 1.15 Funções para arquivos


Descrição

Close Fecha um ou mais arquivos abertos.EOF Indica se chegou o fim do arquivo. A condição exata para determinar o fim

do arquivo depende do tipo de arquivo a ser lido.FileAttr Dado um número de arquivo e um flag, retorna o tipo de acesso para um

arquivo, ou o título de arquivo de sistema operacional para o arquivo.FileCopy Copia um arquivo.FileDateTime Dado um nome de arquivo, retorna uma string que contem a data e a hora

que o arquivo foi criado ou modificadoFileLen Dado um nome de arquivo, retorna seu tamanho em bytesFreeFile Retorna um número de arquivo que pode ser usado para abrí-loGet Usado para ler dados de um arquivo randômico ou binárioGetFileAttr Dado um nome de arquivo ou diretório, retorna seus atributosInput # Dado um número de arquivo, lê dados de um arquivo sequencialInput Dado um número de arquivo, lê um número específico de caracteres de

um arquivo seqüencial ou binário InputB Dado um número de arquivo, lê um número específico de bytes de um

arquivo sequencial ou binárioKill Deleta um arquivoLine Input# Dado um número de arquivo, retorna uma linha de um arquivo sequencialLOC Dado um número de arquivo, retorna a posição do arquivo de ponteiro no

arquivoLock Dado um número de arquivo, loca o arquivo, ou um registro ou uma

seqüência de bytes de um arquivo. Outro processo não pode atualizá-lo(s).LOF Dado um número de arquivo, retorna o tamanho do arquivo

Name Renomeia um arquivo ou diretórioOpen Abre um arquivoPrint # Imprime uma lista de variáveis de um arquivoPut Escreve dados em um arquivo randômico ou binárioReset Fecha todos os arquivos abertosSeek Dado um número de arquivo, retorna a posição atual do arquivo de

ponteiro. Também, dado um número de arquivo e uma posição, posiciona o ponteiro o ponteiro do arquivo de ponteiro

SetFileAttr Altera os atributos de sistema de arquivo de um arquivoSpc Insere um número específico de espaços em um comando Print ou Print(#)Tab Move a posição de impressão para uma coluna específicaWidth # Usado para especificar o tamanho da linha de um arquivoWrite # Escreve uma lista de variáveis para um arquivoUnlock Libera um arquivo locado pelo comando Lock.

LotusScript pode trabalhar com três tipos de arquivos mostrados na tabela 1.16.

Tabela 1.16 Tipos de Arquivos

Tipo de Arquivo DescriçãoSeqüencial Um arquivo de textoRandômico Um arquivo com registros formatadosBinário Um arquivo com uma estrutura de definição de programa

14.1 Obtendo informações de arquivo

Se você tem o nome de um arquivo, você pode usar os comandos GetFileAttr, FileDateTime e FileLen para acessar informações de arquivo. Use GetFileAttr para checar os atributos de um arquivo. A função FileDateTime retorna a data de última modificação do arquivo e FileLen o tamanho do arquivo em bytes. Por exemplo, o código seguinte checa se um arquivo está ocultado, e se estiver, modifica seus atributos de ocultação:

%Incluce “LSCONST.LSS”

Dim iAttributes As Integer

IAttributes = GetFileAttr(“C:\TEMP.TXT”)

If (iAttributes And ATTR_HIDDEN) Then

Call SetFIleAttr(“C:\TEMP.TXT”, ATTR_READONLY)

End If

14.2 Criando e abrindo arquivos

Para abrir um arquivo seqüencial, use os comandos FreeFile e Open. Use FreeFile para alocar um novo número de arquivo para o arquivo. Por exemplo, para abrir um novo arquivo seqüencial para gravação:

Dim iFileNumber As Integer

IFileNumber = FreeFile

Open “C:\RESULTS.TXT” For Output As iFileNumber

Você pode abrir um arquivo seqüencial para leitura e gravação. Um vez o arquivo aberto, você usa o número de arquivo para se referenciar a ele.

Para abrir um arquivo randômico, você usa os comandos FreeFile e Open, e especifica as opções randômicas no comando Open. Por exemplo:



Open “C:\RECORDS.DAT” For Random As iFileNumber Len = 80

A função Len é usada para indicar o número de bytes por registro no arquivo. Use a opção Binary no comando Open para abrir um arquivo binário. Por exemplo:



Open “C:\RECORDS.DAT” For Binary As iFileNumber

Uma vez tendo aberto o arquivo, você pode usar a função LOF para checar o número de bytes no arquivo.

14.3 Lendo arquivos

Você pode usar os comandos Line Input # e Input #, ou a função Input, para ler dados de um arquivo seqüencial aberto. Line Input # lê uma linha de dado de um arquivo. Por exemplo:

Do Until EOF(iFileNumber)

Line Input #iFileNumber, strInputLine

Loop

A função EOF retorna verdadeiro quando chega no fim do arquivo. Use Input # para ler dados de uma linha em um arquivo e colocá-la em um conjunto

de variáveis. Por exemplo, se seu arquivo tem linhas no formato:

14829, “Chris”, “Edwards”, 100.00

25674, “Marlene”, “Metcalfe”, 850.00

Você pode usar o código abaixo para ler a linha de um arquivo:

Dim lID As Long


Dim strSurname As String

Dim curBalance As Currency

‘ . . . Abre um arquivo como no exemplo anterior

Input #iFileNumber, lID, strFirstName, strSurName, curBalance

A função Input é outra opção para ler dados de um arquivo sequencial. Com Input, você fornece o número de caracteres a ler. Por exemplo, você poderia ler o número de ID do início de uma linha no arquivo usando o código seguinte:

StrID = Input$(5,iFileNumber)

Quando você está trabalhando com arquivos binários ou randômicos, use os comandos Seek e Get para achar e ler registros de um arquivo.

14.4 Escrevendo em arquivos

Você pode usar Write # para escrever os conteúdos de um conjunto de variáveis para um arquivo seqüencial. Por exemplo, para escrever uma linha em um arquivo aberto:


Dim strSurname As String

Dim curBalance As Currency

‘ . . . Abre o arquivo para gravação como no exemplo anterior

‘ . . . Adiciona valores para as variáveis

Write #iFileNumber, lID, strFirstName, strSurname, curBalance

Write # automaticamente adiciona caracteres formatados para a linha de gravação onde os valores estarão separados por vírgulas. Você também pode usar o comando Print # para escrever dados em um arquivo sequencial. Porém, quando você usa Print #, você deve adicionar seus próprios caracteres formatados. Há poucas funções que você pode usar com Print # para ajudar a formatar a linha. Use Spc para adicionar um número específico de espaços na linha e Tab para mover a posição de impressão para uma posição específica na linha. Por exemplo:

StrFirstName = “Pat”

StrSurname = “Green”

Print #iFileNumber, “*”; Tab(4); strFirstname; Spc(2); strSuname;”*”‘ Grava Pat Green

Use Put para escrever dados em arquivos binários ou randômicos. Em alguns casos você pode querer bloquear acesso a um arquivo até seu programa

terminar de usá-lo. LotusScript proporciona os comandos Lock e UnLock para você fazer isso.

14.5 Fechando arquivos

Ao terminar de usar um arquivo, você pode fechá-lo usando o comando Close. Se você quer fechar todos os arquivos que estão abertos, você pode usar o comando Reset.

14.6 Excluindo arquivos

Para deletar um arquivo use o comando Kill. Use o comando com o nome do arquivo como se segue:

Kill “C:\TEMP.TXT”

15 Leitura/Gravação

Quando você está usando LotusScript com Notes, você muitas vezes usa formulários Notes para obter informações de usuários e exibir os resultados. Mas, algumas vezes, você precisa usar métodos diferentes para se comunicar com o usuário. As funções mostradas na tabela 1.17 oferece a você algumas alternativas:

Tabela 1.17 Funções de Leitura/Gravação


Descrição

Beep Alarma InputBox Mostra uma caixa de diálogo onde o usuário pode entrar com um

valorMessageBox Mostra uma caixa de mensagem ao usuárioPrint Escreve algum texto na barra de status do Notes

Use InputBox para mostrar uma caixa de diálogo com um campo de entrada. O usuário pode entrar com uma string no campo e clicar OK. Você pode acessar a string digitada como se segue:

StrName = InputBox$(“ Por favor, entre com su nome “)

Se você quiser, você pode espesificar um título para a caixa de diálogo. Por exemplo:

IOrderQuantity = Cint(InputBox$(Entre com a quantidade requisitada”, “ Quantidade

requisitada”, “10”)

Você pode mostrar valores de seu código usando tanto a função MessageBox como Print. Use MessageBox para exibir uma caixa de diálogo contento uma mensagem de sua escolha. Por exemplo, se você quer mostrar uma mensagem para confirmar o pedido, você pode usar:

MessageBox( “Você está para confirmar um pedido ” & & CStr(iOrderQuantity) & “

Está correto?”, MB_YESNO, “ Confirmar pedido “)

A constante MB_YESNO é uma entre muitas constantes relativas a função MessageBox, definida no arquivo LSCONST.LSS. Constantes adicionais estão disponíveis

e você pode usar para adicionar ícones e botões a caixa de diálogo. Veja a ‘MsgBox parameters’ no arquivo LSCONST.LSS para mais detalhes.

A função Print exibe uma linha de texto na barra de status do Notes. Isto pode ser bastante interessante se você está escrevendo um agente LotusScript que pode levar algum tempo para executar, porque isto pode lhe dar uma forma para manter o usuário informado sobre o progresso do agente. Por exemplo, em um agente que processa documentos em um banco de dados, você pode usar:

Print “ Documento processando “ & CStr(iCurDoc) & “ de “& CStr(iTotalDocs) & “ . . .

O código fica dentro do loop de processamento principal mostrando uma constante atualização da mensagem contida na barra de status.

16 Funções Mátemáticas

As funções matemáticas do LotusScript são mostradas na tabela 1.18

Tabela 1.18 funções matemáticas


Descrição

Abs Retorna o valor absoluto de um númeroAcos Dado um número entre 1 e –1, retorna seu arco coseno em

radianosAsin Dado um número entre 1 e –1, retorna seu arco seno em radianosAtn Dado um número, retorna sua arco tangente em radianosAtn2 Dado as coordenadas de um ponto no plano cartesiano, retorna o

ângulo em radianosCos Dado um ângulo em radianos, retorna seu coseno Exp Dado um número, retorna o exponencial de um númeroFix Retorna a parte inteira de um númeroFraction Retorna a parte fracional de um númeroInt Retorna o número inteiro que é menor ou igual ao fornecidoLog Retorna o logarítmo natural de um númeroRound Arredonda um númeroSgn Retorna –1, 0 ou 1 se o número for negativo, zero ou positivoSin Dado um número em radianos, retorna seu senoSqr Retorna a raiz quadrada de um númeroTan Dado um ângulo em radianos, retorna sua tangente

16.1 Ocultando Erros em Tempo de Execução

LotusScript detecta dois tipos de erros:

• Erros de compilação;

• Erros em tempo de execução.

Erros de compilação são devido erros em seu código de LotusScript. Você não pode executar seu código até consertar todos os erros de compilação detectados. Nós olharemos o Ambiente de Desenvolvilmento Integrado do Notes (IDE) no próximo capítulo e verificar

algumas das características que ajudam a reduzir o número de erros de compilação que você deve consertar.

Erros em tempo de execução são erros que ocorrem quando o código está em execução. Por exemplo, erro ocorre quando o script tenta abrir um arquivo que foi deletado. LotusScript identifica muitos erros em tempo de execução e atribui a cada um um número e uma mensagem de erro descrevendo o erro. Você pode adicionar código aos seus programas para proporcionar ocultação especial para todos os erros. Você pode definir seus próprios erros se quiser e atribuir um número de erro e uma mensagem. A tabela 1.19 mostra as funções que estão relacionadas com ocultação de erros.

Tabela 1.19 Funções de ocultação de erros


Descrição

Erl Retorna o número da linha do erro mais recenteErr Retorna o número do erro dependendo como ele ocorraError Retorna uma mensagem do erro dependendo como ele ocorraOn Error Desvia a execução do código para uma função quando ocorre um erroResume Determina onde o programa recomeça a execução de pois de um erro

Além de detectar um erro em tempo de execução, o LotusScript armazena as seguintes informações:

• O número da linha onde ocorreu o erro;

• O número do erro;

• A mensagem de erro.

Você pode usar a função Erl para obter o número da linha onde ocorreu o erro mais recente. A função Err retorna o número de erro mais recente e Err$ a mensagem de erro associada.

Uma vez o LotusScript tendo armazenado estas informações, ele procura por um comando On Error, no procedimento corrente, que possa ocultar o erro. Se ele não achá-lo, o LotusScript mostra sua própria mensagem de erro associada ao erro que parou a execução do script. Se um comando On Error for achada, LotusScript transfere o controle para ele.

O comando On Error pode também fazer o seguinte:

• Ignorar o erro. Se você especificar On Error Resume Next, é ignorado a linha onde ocorreu o erro e executada a linha logo depois;

• Especifica uma Label para executar seu código. Se você especificar On Error Go To seguido do nome de uma label, o LotusScript transfere o controle para o código na label. O código deve ocultar o erro. Use o comando Resume para reiniciar o script.

O exemplo seguinte mostra como definir seu próprio erro e criar um código que oculte o erro. O exemplo Sub define um erro com número 600 e inicializa a rotina de ocultação do erro que mostra o número do erro e o número da linha onde ocorreu o erro. O controle é então retornado para a linha seguinte a que ocorreu o erro forçado:

Sub ErrorTest

Const ERR_MY_ERROR = 600 ‘ Define um erro

On Error ERR_MY_ERROR GoTo lblHandleError ‘ Define o comando que vai

detectar este erro

Error ERR_MY_ERROR ‘ Força o erro

Print “Finished” ‘ Retorna a execução para este ponto

Exit Sub

LblHandleError:

Print “ Número do erro “; Err; “ ocorreu na linha “ ; Erl

Resume Next

End Sub.

CAPÍTULO 2 - USANDO O LOTUS SCRIPT NO LOTUS NOTES

• Aprenda como usar o Ambiente de Desenvolvimento Integrado do Notes para usar o LotusScript.

Você usa o Ambiente de Desenvolvimento Integrado para entrar, compilar e depurar seus programas do LotusScript.

• Aprenda como usar o editor Script.

O editor Script permite a você entrar e atualizar scripts. Ele entende a sintaxe do LotusScript e lhe ajuda formatando automaticamente seu código e checando erros de sintaxe à medida que você digita.

• Aprenda como usar o depurador do LotusScript.

O depurador do LotusScript é uma poderosa ferramenta que você pode usar para examinar seus programas LotusScript que estão rodando. Você pode percorrer seu código uma linha por vez, se necessário, bem como checar e atualizar conteúdos de variáveis a qualquer momento.

• Veja as técnicas de depuração do LotusScript.

Examinamos algumas técnicas úteis que você pode utilizar quando está testando e depurando programas LotusScript.

• Entendendo como acessar bibliotecas de links dinâmicos no LotusScript

Você pode extender o poder do LotusScript chamando as funções dentro de bibliotecas de links dinâmicos. Nós olharemos como fazer isto.

• Aprenda como incluir extensões LotusScript em seus scripts.

Extensões de LotusScript são adicionais as características básicas do LotusScript.

Capítulo 1, “LotusScript Básico”, introduziu você ao LotusScript e explicou algumas de suas característica básicas e sintaxe. Neste capítulo você usará estas características e aprende como usar o LotusScript com o Notes.

O LotusScript estende a interface de programação do Notes além de @functions e @commands. Você usa o LotusScript para escrever scripts para executar várias funções e tarefas no Notes. Você adiciona scripts à vários objetos no Notes, dependendo do que você necessita alcançar. Por exemplo você pode usar o LotusScript para criar um agente para atualizar documentos de forma programada. O LotusScript proporciona algumas capacidades que as fórmulas do Notes não têm, como a habilidade de manipular bancos de dados ACL do Notes, e a habilidade de imprimir uma lista de todos os bancos de dados que residem em um servidor ou disco rígido local. Você entra com o código LotusScript dentro do Notes usando o Ambiente de Desenvolvimento Integrado do Notes(IDE). O Notes contém um compilador LotusScript integral que traduz seu código em um LotusScript executável. Neste capítulo você irá:

• Aprender como usar o Ambiente de Desenvolvimento Integrado do Notes para usar o LotusScript;

• Aprender como usar o editor Script;

• Aprender como usar o depurador do LotusScript;

• Ver algumas técnicas de depuração do LotusScript;

• Entender como acessar Bibliotecas de Links Dinâmicos (DLL) a partir do LotusScript.

• Aprender como incluir extensões de LotusScript no seu script

1 Ambiente de Desenvolvimento Integrado do Notes

O Ambiente de Desenvolvimento Integrado no Notes (IDE) permite à você criar formulários, visões e agentes de maneira consistente. No entanto, para cada formulário, visão ou agente que você crie, você utilizará um diferente IDE. Apesar de cada IDE ser diferente, eles compartilham muitas características comuns, tais como o Editor Script e características do Depurador. Descreveremos o IDE para Formulários, mas o Editor Script e o Depurador trabalham de forma similar nos outros IDE’s. Os IDE’s de Formulários são mostrados conforme a Figura 2.1.

Figura 2.1

Aqui está um exemplo de Formulários IDE.

A tela está dividida em três áreas ou janelas.

1.1 Área de Layout do Formulário

A janela no lado esquerdo superior da tela é a Janela de Layout do Formulário (Form Layout Pane). Você usa esta área para criar o layout de seu formulário.

1.2 Painel de Ação

O painel no lado direito superior da tela é a Janela de Ação (Action Pane). Você pode usar esta janela para definir as ações que estão associadas ao formulário. Por default, a Janela de Ação não é visível quando você abre o IDE pela primeira vez. Para mostrar a Janela de Ação, selecione menu Exibir/Painel de Ação utilizando a barra de menu do Notes, ou arraste a barra vertical da borda direita da tela para a esquerda até que a janela de Ação esteja do tamanho que você deseja. Finalmente, se você é um fã do “SmartIcon” você pode clicar as janelas Exibir /Mostrar/Hide Action usando o SmartIcon.

Para esconder a janela de Ação, você pode tanto selecionar as janelas Exibir/Painel de Ação novamente para desabilitar o menu de opções como arrastar a barra vertical para o lado direito da tela ou pode clicar no botão Exibir/Mostrar/Ocultar Painel de Ação usando o SmartIcon.

1.3 Painel de Estrutura

O Painel de Estrutura é o painel mostrada na parte inferior da tela. É nesta área que você digita seu código do LotusScript. Por default, o Painel de Estrutura é visível. Se você deseja ocultá-la, selecione as janelas Exibir/Painel de Estrutura utilizando a barra de menu do Notes ou arraste a barra horizontal (aquela que separa o Painel de Estrutura do restante da janela) para baixo da parte inferior da tela.

O Painel de Estrutura consiste de um número de componentes que você usa para digitar o seu código do LotusScript. Vamos ver cada um por vez.

1.3.1 Caixa de Desenho

A Caixa de Desenho, mostrada na figura 2.2, é uma caixa “drop-down” que você usa para selecionar o objeto ou a ação que você deseja programar.

Figura 2.2

A Caixa de Definição mostra o nome do objeto ou ação que você está programando.

Por exemplo, a Figura 2.2 mostra que o objeto formulário está constantemente sendo programado para exibir uma mensagem no seu título. Você pode usar a Caixa de Definição para escolher rapidamente outro objeto ou ação. Para programar um objeto diferente, clique a seta da Caixa de Definição. Será exibido uma lista de ações ou objetos que você pode programar como mostrado na Figura 2.3. Então, selecione o objeto ou ação que você deseja programar.

Figura 2.3

Usando a Caixa de Definição para selecionar um objeto para programar.

1.3.2 Caixa de Eventos

O Painel de Estrutura contém uma segunda caixa “drop-down”, a Caixa de Evento, como mostrado na Figura 2.4.

Fig. 2.4

A Caixa de Eventos mostra o nome do evento que você está programando.

A Caixa de Evento mostra tudo dos eventos que estão associados com o objeto ou ação correntemente selecionados. A Caixa de Evento mostra o evento correntemente sendo programado. Por exemplo, na Figura 2.4, o evento que está sendo programado é o evento “Título da Janela” no formulário. Para programar um evento diferente, simplesmente selecione-o da lista contida na Caixa de Evento.

Note que se o objeto ou ação selecionados não possuam eventos associados com eles, tais como uma das ações de formulários padrões, a Caixa de Eventos não é mostrada. A Figura 2.5 mostra a aparência do Painel de Estrututa quando a ação do documento de edição padrão é selecionada.

Figura 2.5

Este é a aparência do Painel de Estrututa quando uma ação de formulário padrão é selecionada.

NOTA

Se você adicionar suas próprias funções e “subs” LotusScript à um formulário, eles serão mostrados na Caixa de Evento quando você selecionar os objetos Globais para o formulário.

1.3.3 Run Radio Button

Dependendo do tipo do objeto que você selecionou na Caixa de Definição, você pode usar o “Run Radio Button”(Figura 2.6) para selecionar o tipo de programação para o objeto (veja Figura 2.6). Você possui três escolhas:

• Ação(ões) Simple(s)

• Fórmula

• Script

Figura 2.6

O Run Radio buttons deixa-o selecionar LotusScript como uma opção de programação

1.3.4 O Script Browser

Depois que você selecionar o botão “Script radio” você poderá mostrar o Script Browser através da caixa de visualização do Browser (Show Browser Check Box). O Script Browser é mostrado na Figura 2.7.

Figura 2.7

Este é o Script Browser.

O browser permite-lhe mostrar o seguinte:

• Uma lista de funções e características disponíveis no LotusScript.

• Todas as classes do Notes e seus métodos, propriedades e eventos associados (falaremos de todos esses assuntos no próximo capítulo).

• Todas as classes “OLE2” e “ActuveX” que estão disponíveis para você.

Você seleciona o que você deseja mostrar usando “browser combo box”. Você pode selecionar o seguinte:

• Linguagem LotusScript

• Classes do Notes

• Constantes do Notes

• Funções e subs do Notes

• Variáveis do Notes

• Classes OLE2

Por exemplo, se você deseja ver quais as funções que o LotusScript tem disponíveis para tratar erros, siga os seguintes passos:

1. Se a opção ainda não estiver selecionada, selecione Linguagem LotusScript no browser combo box. Uma lista de categorias de funções será mostrada;

2. Clique na seta próximo Tratamento de Erros (Error Handling). Os nomes e sintaxe das funções de Tratamento de Erros do LotusScript serão mostradas (veja Figura 2.8).

Fig. 2.8

As funções de Tratamento de Erros (Error-handling functions) do LotusScript mostradas no Script Browser.

Se você deseja adicionar um item do browser ao código, (tal como um nome de função), siga os seguintes passos:

1. Posicione o cursor no código do LotusScript aonde você deseja inserir o item;

2. No Script Browser, clique duas vezes no item que deseja inserir. O item é inserido dentro do código aonde você colocou o cursor.

O browser pode ser muito útil quando você deseja fazer o seguinte:

• Checar a disponibilidade de uma função específica;

• Checar parâmetros para uma função;

• Checar as propriedades, métodos e eventos de uma classe Notes, OLE2 ou ActiveX.

1.3.5 O Editor Script

Você vai digitar seu código de LotusScript na área de Painel de Estrutura chamada o Editor Script. O Editor Script entende a sintaxe do LotusScript e lhe ajuda revisando o script assim que você digita. O Editor Script:

• Checa erros de sintaxe assim que você entra no Script;

• Automaticamente torna maiúsculas palavras chaves do LotusScript;

• Formata o script indentando automaticamente blocos do código;

• Completa certos tipos de “statements”, do tipo “If...Then” e “For...Next” loops;

• Fornece cores para mostrar diferentes tipos de expressões no seu script.

Veremos mais detalhadamente como usar o Editor Script posteriormente neste capítulo.

1.3.6 Caixa de Erros

A Caixa de Erros (Error combo box) é usada para mostrar erros de sintaxe e compilação. Por exemplo, Figura 2.9 mostra como um simples erro de sintaxe é detectado e apresentado.

Fig. 2.9

Como um erro de sintaxe é mostrado.

2 Usando o Editor Script

Se você pode usar um editor de texto, você pode usar o Editor Script! Ele trabalha exatamente igual à maioria dos editores de texto e contém as combinações familiares de teclas para mover o cursor e para cortar, copiar e colar textos. Por exemplo:

• “Home” move o cursor para o início da linha corrente.

• “End” move o cursor para o fim da linha corrente.

• “Ctrl+C” copia o texto selecionado

• “Ctrl+V” cola o texto selecionado

CUIDADO

O Editor Script não tem a função “Undo”, então tenha cuidado quando estiver editando algo.

2.1 Configurando o Editor Script

Novo para o Editor Script apartir da versão 4.5 do Notes é sua habilidade para escolher a fonte usada pelo mesmo e para mostrar diferentes tipos de “statements” em cores diferentes. Você pode escolher a cor para:

• Identificadores;

• Palavras chave;

• Comentários;

• Diretivas;

• Erros.

Para definir fontes e cores, siga os seguintes passos:

1. “Right-click” no Editor Script. Um menu “Pop-up” será mostrado.

2. Selecione propriedades na janela de Desenho. As propriedades da janela de Desenho são mostradas nas propriedades “InfoBox”, como mostrado na Figura 2.10.

Fig. 2.10

Você usa as Propriedades “InfoBox” da Painel de Estrutura para configurar o Editor Script.

1. Selecione o “Script radio buttom”.

2. Selecione o tipo e tamanho da fonte que você deseja usar.

3. Escolha uma cor para cada tipo de expressão.

2.2 Dando entrada em um código

Siga os seguintes passos para dar entrada em um código:

1. Selecione o objeto ou ação com os quais você deseja trabalhar;

2. Selecione o evento ao qual o código será anexado;

3. Digite o código no Editor Script.

Você pode selecionar o objeto ou a ação para serem programados de diferentes formas. Por exemplo, para selecionar um objeto você pode escolher uma das seguintes opções:

• Selecione o nome do objeto utilizando a “drop-down list” na caixa de definição;

• Clique no objeto na Janela de Layout de formulário.

Para selecionar uma ação para programar você pode escolher uma das seguintes opções:

• Selecione o nome da ação utilizando a “drop-down list” na caixa de definição;

• Clique na ação na Janela de ação.

O Editor Script checa automaticamente a sintaxe de seus códigos assim que você entra com eles. Por exemplo, na hora que você comete um erro de digitação, o Editor Script lhe dá conhecimento mostrando o erro na caixa de erros. Se você tiver configurado as cores para o Editor Script, o erro é sublinhado na cor que você escolheu para erros. Palavras-chave, identificadores, comentários e diretivas também serão sublinhados na cor escolhida.

O código que você dá entrada utilizando o Editor Script é armazenado no módulo do LotusScript. O Notes armazena um módulo separado para cada formulário, visão e agente que você cria. Alguns dos nomes listados na Caixa de Definição referem-se mais a partes do módulo LotusScript que a objetos e ações. As partes do que você usa são:

• A parte (Options) da seção (Globals);

• A parte (Declaration) da seção (Globals).

Você usa parte Options para definir opções que afetam o código LotusScript que você está digitando. Por exemplo, se você deseja usar a expressão Option Declare para assegurar que todos os nomes variáveis estão declarados, você os adiciona na parte

Options da seção Globals. A seção Declarations é onde você define os tipos de dados e variáveis usados pelo seu módulo.

O Editor Script tenta completar blocos de códigos e os move para a posição correta. Por exemplo, se você começa uma definição de tipo em uma nova linha do seu Script escrevendo Type MyTypeName e pressionando Enter, o Editor Script automaticamente o move para a parte Declaration e adiciona a expressão End Type. O Editor Script automaticamente move os blocos de códigos seguintes ao local correto.

• Type – Entre com TYPE seguido do nome e pressione Enter. O Editor Script cria um bloco Type...End Type vazio e o adiciona ao final da seção Declarations;

• Dim – Se você digitar uma expressão Dim em qualquer lugar fora de um sub ou função, o Editor Scritpt move a expressão Dim para o fim da seção Declaration;

• Function – Digite Function seguido do nome da função e pressione Enter. O Editor Script cria um bloco Function...End Function vazio e adiciona o nome da função à Caixa de Evento;

• Sub – Digite Sub seguido do nome do Sub e pressione Enter. O Editor Script cria um bloco Sub...End Sub vazio e adiciona o nome do Sub à Caixa de Evento;

• Option – Digite uma das expressões Option do LotusScript, tais como Option Declare ou Option Base e o Editor Script move a expressão para o fim da seção Options;

• Class - Se você começa uma definição de classe digitando Class seguido por um nome de classe e pressionando Enter, o Editor Script move a definição para a seção Declaration e adiciona um End Class statement para você;

• Property – Tanto para Property Set como para Property Get, o Editor Script automaticamente cria um novo bloco de propriedades e adiciona o seu nome para a Caixa de Evento.

O Editor Scritpt também completa os seguintes blocos de códigos para você:

• For loops – Digite na primeira linha de um “loop” e pressione Enter. A terminação “Next” é automaticamente adicionada para você;

• Forall loops – A terminação End Forall é adicionada quando você pressiona Enter após a digitação da primeira linha;

• Expressões If – O End If é adicionado para você;

• Expressões Select - O End Select é automaticamente adicionado.

• Do While loops – A terminação “Loop statement” é adicionada;

• Statments While – A terminação Wend é adicionada.

2.3 Compilando um Script

O Editor Script automaticamente compila seu LotusScript. Ele o faz nos seguintes momentos:

• Assim que você dá entrada no Script, o Editor Script parcialmente compila o script. É assim que ele detecta erros e sabe quando completar blocos de códigos;

• Quando você salva o script ou quando você clica fora do Editor Script, o Editor Script compila o módulo inteiro do LotusScript. Ele encontra aqueles erros que não pode detectar durante compilações parciais. Por exemplo, este é o momento que pode ser detectada uma chamada para uma função ou sub não existente.

Você não pode salvar um script que contém erros de compilação, você deve corrigir todos antes de salvar o script.

DICA

Se você quer salvar um script contendo erros você pode colocar diretivas “%REM” e “%END REM” em volta da parte do script que contém erros. Este comentário oculta o erro e permite-lhe salvar o script.

3 Usando o LotusScript com o Notes

O Notes usa um modelo de programação orientado a objeto e a evento. A Interface entre o LotusScript e o Notes é através de um conjunto de classes de objeto, as classes de objetos Notes. Objetos de cada classe geram e respondem a diferentes eventos. Por exemplo, o objeto botão pode responder ao ser pressionado, ou o objeto campo pode responder com o cursor sendo posicionado no mesmo. Quando você programa usando o LotusScript no Notes, você cria um LotusScript que responde a esses eventos.

Você pode anexar o LotusScript a eventos nos seguintes tipos de objetos:

• Botões;

• Ações;

• Pontos de Acesso;

• Campos;

• Formulários;

• Visões e Pastas;

• Banco de Dados;

• Agentes.

Para cada objeto, você precisa conhecer os eventos aos quais ele (objeto) responde.

3.1 Botões, Ações e “Pontos de Acesso”

Botões, ações e Pontos de Acesso respondem aos eventos mostrados na tabela 2.1. O evento Click é o que você vai usar com maior freqüência. Ele é gerado sempre que botão, ação ou ponto de acesso são clicados. O evento ObjectExecute é criado para que uma aplicação de servidor OLE2 possa usar o NotesFlow para executar ações do Notes.

Tabela 2.1 Eventos Botão, Ação e Ponto de Acesso

Evento Trigger

Click Quando é selecionado botão, ação ou ponto de acesso

ObjectExecute Quando a ação é ativada por um servidor OLE2 que usa FX/NotesFlow para executar ações.

O exemplo seguinte mostra como adicionar um botão e escrever LotusScript para tratar o evento “Click”.

1. Crie um novo banco de dados vazio;

2. Crie um novo formulário no banco de dados. A estrutura do formulário é mostrada;

3. Selecione “Criar - Ponto de Acesso - Botão”. Um botão é adicionado ao formulário e a caixa de informação com suas propriedades são mostradas;

4. Dê um título ao botão digitando “Ola turma” no campo “Rótulo do botão”;

5. Clique na janela do editor de Script;

6. Selecione o “Script radio buttom”. Pelo padrão (default), a posição fórmula é selecionada para um novo botão;

7. Adicione o seguinte código ao evento “Click”.

Messagebox “Olá Turma !”, 0, “Botão de teste”.

8. Selecione a opção “Estrututa – Visualizar no Notes”. Você é solicitado a entrar com o nome para o novo formulário;

9. Entre com “Test” como o nome do formulário e clique OK. O novo formulário é salvo e mostrado.

10. Clique o botão “Olá Turma”. Sua caixa de mensagem “Olá Turma” é mostrada.

3.2 Campos

Você pode anexar o LotusScript aos eventos de campos mostrados na tabela 2.2.

Tabela 2.2 Eventos de campos

Evento Trigger

Entering Quando um usuário coloca o curso no campo.

Exiting Quando o cursor é movido para fora do campo.

O evento Entering é útil para responder ao usuário colocando o cursor no campo. Por exemplo, assim que um usuário coloca o cursor em um campo, você pode colocar alguns dados dentro do campo ou limpar seu conteúdo. Você pode usar o evento Exiting para ver se um campo foi corretamente preenchido assim que o usuário move o cursor para fora do campo, ao invés de esperar até que o documento seja salvo. Os exemplos seguintes mostram como usar o Existing para ajudar a validar o campo:


2. Crie um novo formulário no banco de dados. A estrutura do formulário é mostrado;

3. Selecione “Create”, “Field”. Um campo é adicionado ao formulário e sua caixa de propriedades é mostradas;

4. Use a caixa para dar ao campo o nome “ProductID”.;

5. Clique na janela do Editor Script;

6. Na caixa de Eventos, selecione o evento “Exiting”;

7. Dê entrada no seguinte script.

Sub Exiting (Source as Field)

Dim uiWorkspace As New NotesUIWorkspace (cria uma área de trabalho)

Dim uiDoc As NotesUIDocument (cria um objeto do tipo documento atual)

Dim strProductId As String (cria um campo)

Set uiDoc = uiWorkspace. CurrentDocument (atribui o documento atual ao objeto)

StrProductId = uiDoc.FieldGetText (“ProductID”) (atribui o valor do campo do

objeto a variável)

If Len(strProductID) <> 5 Then

Messagebox “Please enter a five character product ID”, 0, “Re-enter Product ID”

Call uiDoc.GotoField (“ProductID”) (coloca o cursor no campo ProductID)

End If

Call uiDoc.FieldSetText (“ProductID”, strProductID) (atribui o valor da variável

ao campo)

End Sub

8. Salve e teste o formulário. Coloque o cursor no campo “ProductID” and pressione “tab”para mover para o campo “ProductName”.

3.3 Formulários

O objeto formulário (NotesUIDocument) responde aos eventos listados na tabela 2.3. O evento QueryOpen ocorre quando uma solicitação foi feita para abrir um documento. Você pode usá-lo para estabelecer valores padrões (default) no documento, por exemplo, procurando um conjunto de valores de um banco de dados externo. Você pode também usar QueryOpen para ver se você deve permitir que um documento seja aberto. Por exemplo, você pode ver quem está tentando abrir o documento ou seu status atual antes de permitir que ele seja aberto. Imediatamente após a abertura do documento o evento PostOpen ocorre. PostOpen conserva um histórico de quem leu o documento adicionando o nome das pessoas à uma lista cada vez que um evento PostOpen ocorre.

Tabela 2.3 Eventos de Formulários

Evento Trigger

PostModeChange Após o formulário ser alterado para ou a partir do modo de edição.

PostOpen Após o formulário ser aberto.

PostRecalc Após o formulário ter sido atualizado.QueryClose Antes do formulário ser fechado.

QueryModeChange Antes do formulário ser alterado para ou a partir do modo de edição.

QueryOpen Antes do formulário ser aberto.

QuerySave Antes do formulário ser salvo.

Quando um documento é aberto, os eventos QueryModeChange e PostModeChange permitem-lhe responder ao documento que está sendo mudado para e a partir do modo de edição. QueryModeChange ocorre imediatamente antes do documento alterar de um modo para outro (tanto de edição para leitura como de leitura para edição). PostModeChange ocorre imediatamente após. Você pode usar QueryModeChange para decidir se um usuário deve editar um documento. Por exemplo, se um documento em um sistema “Workflow” foi marcado como um documento aprovado, QueryModeChange pode suspender sua edição.

O evento PostRecalc ocorre após todas as fórmulas em um documento terem sido recalculadas. QueryClose e QuerySave permite-lhe responder a uma requisição de usuário para fechar ou salvar um documento. Por exemplo, você pode usar QuerySave para checar que todos os campos em um documento foram preenchidos corretamente.

O exemplo seguinte mostra como usar o evento PostOpen para manter uma lista das pessoas que editaram um documento:


2. Crie um novo formulário no banco de dados. A estrutura do formulário é mostrada;

3. Selecione “Criar – Campo”. Um campo é adicionado ao formulário e sua caixa de propriedade é mostrada;

4. Use a caixa para dar ao campo o nome DocEditors;

5. Clique na janela do editor de script;

6. Na caixa de Definição, selecione “Sem Título” (Formulário), então selecione Postmodechange na caixa de eventos;

7. Dê entrada os seguintes códigos:

Sub Postmodechange (Source As Notesuidocument)

Dim s As New NotesSession*

If Source. EditMode Then ( Verifica se o documento está em modo de edição)

Call Source.FieldAppendText (“DocEditors”, s.CommonUserName & Chr(10)) (Adiciona o nome comum do usuário corrente ao campo DocEditors. )

End If

End Sub

*Representa o ambiente do script corrente, proporcionando acesso a variáveis de ambiente, “address books”, informações a respeito do usuário corrente e sobre a plataforma Notes corrente e a sua versão.

8. Salve o formulário;

9. Crie um documento usando o formulário e salve-o;

10. Edite o documento. Seu nome é automaticamente adicionado ao campo “DocEditors” cada vez que você edita o documento.

3.4 Visões e Folders

O objeto visão e pasta (veja a classe NotesUIView no Capítulo 3) é novo e surgiu na versão 4.5. do Notes. Este objeto responde aos eventos listados na tabela 2.4. O QueryOpen ocorre imediatamente antes de uma visão ser aberta. O PostOpen ocorre imediatamente após uma visão ter sido aberta. Quando um usuário tenta abrir um documento mostrado na visão, o evento QueryOpenDocument ocorre. Você pode usar este evento para ver se um documento deve ser aberto, ou para solicitar ao usuário que dê entrada em algumas informações antes que ele possa ver o documento.

Tabela 2.4 Evento Visão e Folder

Evento Trigger

PostDragDrop Após uma operação “arrastar e soltar” (somente visões de calendário).

PostOpen Após a visão ter sido aberta.

PostPaste Após um documento ter sido colado dentro de uma visão.

QueryAddToFolder Antes de um documento ser adicionado a um pasta.

QueryClose Antes da visão ser fechada.

QueryDragDrop Antes de uma operação “arrastar e soltar” (somente visões de calendário).

QueryOpen Antes da visão ser aberta.

QueryOpenDocument Antes de um documento ser aberto a partir da visão.

QueryPaste Antes de um documento ser colado dentro de uma visão.

QueryRecalc Antes da visão ser recalculada.

RegionDoubleClick Após uma região ter recebido um duplo-clique

Existem dois eventos que você pode usar para processar documentos que são colados em uma visão. QueryPaste ocorre imediatamente antes de um documento ou conjunto de documentos serem colados dentro de uma visão; PostPaste ocorre imediatamente após. Você pode usar PostPaste para disparar processamento específico de documentos que tenham sido colados na visão. Por exemplo, você pode armazenar a data e a hora que os documentos foram colados na visão. O evento QueryAddToFolder ocorre imediatamente antes de um documento ser copiado para uma pasta. Você pode usá-lo para checar se o documento pode ser adicionado a uma pasta ou para solicitar ao usuário que entre com algumas informações sobre o documento. QueryRecalc ocorre imediatamente antes de uma visão ser recalculada e lhe dá a oportunidade de parar o recálculo. O evento QueryClose ocorre imediatamente antes da visão ser fechada.

Existem três eventos que são designados para uso com visão do tipo calendário. QueryDragDrop e PostDragDrop ocorre imediatamente antes e imediatamente após a uma operação “arrastar e soltar”. Você pode usá-los para decidir se permite que a operação “arrastar e soltar” continue ou para realizar algum processamento após a operação ter sido completada. RegionDoubleClick ocorre quando um usuário dá um duplo-clique em uma região de dados em uma visão de calendário.

Os passos seguintes mostram como usar o evento PostPaste para armazenar a data e a hora que o documento é colado dentro de um folder:

1. Crie um novo banco de dados de discussão a partir do modelo “Discussion (R4)”;

2. Selecione “Estrutura – Pasta” e abra a pasta “Meus Favoritos” no modo estrutura;

3. Selecione o evento PostPaste na caixa de evento;

4. Dê entrada no código seguinte:

Sub Postpaste (Source As Notesuiview) (source representa a visão corrente)

Dim iDoc As Integer

Dim doc As NotesDocument (classe que representa um documento no BD)

For iDoc = 1 To Source.Documents.Count (percorre os documentos da coleção)

Set doc = Source.Documents.GetNthDocument (iDoc) (retorna um documento na

posição “idoc”)

Doc.Data = Now

Call doc.Save(True, True) (salva mudanças feitas em um documento)

Next

End Sub

5. Salve a pasta;

6. Crie um novo documento Tópico Principal e salve-o;

7. Selecione-o e copie-o para a área de transferência;

8. Mude para a pasta “Minhas Favoritas” e cole o documento.

9. Cheque as propriedades para o documento. A data e a hora que você colou o documento são armazenadas em um novo campo chamado “Data”.

3.5 Bancos de Dados

Bancos de Dados (veja a classe NotesUIDatabase no Capítulo 3) respondem a seis eventos mostrados na tabela 2.5. O evento PostOpen ocorre depois do banco de dados ser aberto.

NOTA

O evento PostOpen para banco de dados ocorre após os eventos QueryOpen e PostOpen para abertura de visão.

Tabela 2.5 Evento Banco de Dados

Evento O evento é disparado...

PostDocumentDelete Após um documento ter sido excluído do banco de dados usando “Cortar” ou “Limpar”.

PostOpen Após o banco de dados ter sido aberta.

QueryClose Antes do Banco de Dados ser fechado.

QueryDocumentDelete Antes de um documento ou grupo de documentos ser excluído do

banco de dados.

QueryDocumentUndelete Antes de um documento ou grupo de documentos ser recuperado .

O evento QueryDocumentDelete ocorre imediatamente antes de um ou mais documentos serem excluídos do banco de dados. PostDocumentDelete ocorre imediatamente após os documentos terem sido excluídos. O evento QueryDocumentUndelete ocorre quando um documento ou conjunto de documentos (que tenham sido marcados para exclusão) são desmarcados. QueryClose ocorre imediatamente antes do banco de dados ter sido fechado.

Os passos seguintes mostram como usar a mensagem PostDocumentDelete para enviar correspondência automaticamente para alguém quando documentos são apagados de um banco de dados:

1. Crie um novo banco de dados de discussão a partir do “Discussion (R4) template”;

2. Selecione “Estrutura - Outros“ e abra o Script do Banco de Dados;

3. Selecione o evento PostDocumentDelete na caixa de evento;

4. Dê entrada no código seguinte:

Sub Postdocumentdelete (Source As Notesuidatabase)


Dim doc As NotesDocument

Set db = Source.Database

Set doc = New NotesDocument (db)

doc.SaveMessageOnSend = False (não salva a mensagem de envio)

doc.Form = “Memo”

doc.SendTo = “Marcio Nogueira”

doc.Subject = CStr(Source.Documents.Count) & “ documents deleted at “

& CStr(Now) & “.

“Call doc.Send( True ) (envia a mensagem)

End Sub

5. Salve o script;

6. Feche o banco de dados e reabra-o;

7. Crie um novo documento Tópico Principal e salve-o;

8. Mude para a visão “Todos os Documentos”, selecione o documento que você acabou de criar e marque-o para exclusão;

9. Feche o banco de dados e exclua o documento criado recentemente;

10. Uma mensagem de correio é automaticamente criada e enviada;

3.5 Agentes

Um agente é um procedimento de usuário que você pode usar para automatizar muitas tarefas dentro do Notes, tais como o arquivamento de documentos antigos ou a geração automática de cópias para enviar mensagens. Um agente pode ser disparado de várias maneiras, incluindo comando de menu, uma lista predefinida, a chegada de uma correspondência, ou documentos sendo colados. Você pode criar programas LotusScript para criar agentes, e você pode também usar agentes “Notes-Supplied”.

Os agentes executam em qualquer uma das seguintes localizações:

• Estação de trabalho do usuário, se os triggers de agentes tiverem sido definidos para uma das seguintes opções: Manualmente pelo Menu de Ações, Manualmente pela Lista de Agente, “se Documentos tiverem sido Criados ou Modificados” ou “se Documentos tiverem sido Colados”;

• servidor ou a estação de trabalho contendo o agente se os triggers dos agentes tiverem sido definidos tanto “Se Nova Correspondência tiver Chegado” ou “Em Fila”.

3.6 Inicializar

Sempre que um agente é executado, ele executa o código anexado ao evento Inicialize. Logo, este é o local onde você deve colocar seu código de agente (veja Tabela 2.6).

Tabela 2.6 Evento Agente

Evento Trigger

Initialize Quando o agente é iniciado.

Terminate Quando o agente é terminado.

4 Usando o Depurador

O depurador lhe permite checar como um script é executado, linha à linha se você quiser. Você pode iniciar e parar o script à qualquer momento e checar os valores que tenham sido atribuídos às variáveis ou propriedades específicas. Isto pode ajudá-lo a encontrar, rapidamente, erros naqueles scripts que estão sendo conduzindos de forma imprópria. O depurador abre sua própria janela mostrando o script sendo executado. Uma seta indica qual a linha do script que está para ser executada e à medida que as linhas são executadas a seta move-se para a próxima linha. Você pode usar o depurador para o seguinte:

• Percorrer o script uma linha por vez;

• Definir pontos de parada no script de forma que o script temporariamente pare de executar em cada ponto de parada (breakpoint);

• Examinar e modificar o valor das variáveis e propriedades.

4.1 Habilitando o Depurador

Quando você deseja iniciar a depuração, você o habilita selecionando “Arquivo – Ferramentas - Depurador LotusScript” através da barra de menu do Notes como mostrado na Figura 2.11.

Figura 2.11

Esta figura mostra como habilitar um depurador.

Para desabilitar o depurador simplesmente selecione “Arquivo – Ferramentas - Depurador LotusScript” novamente.

Uma vez que o depurador é habilitado, ele inicia automaticamente quando você executa qualquer LotusScript. Quando o depurador inicia, ele fará o seguinte:

• Mostra a janela de depuração (veja Figura 2.12);

• Sublinha a primeira linha do script;

• Pausa a Execução do script na primeira linha.

A janela de depuração contém um número de áreas que veremos uma de cada vez.

Figura 2.12

4.2 A Área de Botão

Você pode controlar como o depurador salta um script usando os cinco botões no topo da tela. Os botões trabalham da seguinte forma:

• Continuar - Continua a execução do script até você encontrar o ponto de quebra ou o fim do código encontrado;

• Próximo Passo - Executa o comando atual e para no próximo. Se o comando atual é uma chamada a um sub ou função, para no primeiro comando executável no sub ou função. Além de clicar o botão, você pode usar “Próximo Passo” selecionando “Depurar – Próximo Passo” ou pressionando F8;

• Rastrear por Bloco - Executa o comando atual. Se o comando atual é uma chamada a um sub ou função, execute o sub ou função e para no primeiro comando imediatamente após à chamada. Se o comando não é uma chamada de sub ou função, execute o comando e pare no próximo comando. Você pode clicar no botão “Rastrear por Bloco”, selecionar “Depurar - Rastrear por Bloco” ou pressionar Shift+F8 para usar “Rastrear por Bloco”;

• Rastrear e Sair – Continua a execução do sub ou função até que o final dos mesmos seja alcançado, então pare no comando imediatamente seguinte ao que

chamou o sub ou função. Use “Rastrear e Sair” clicando o botão “Rastrear e Sair”, selecionando “Depurar - Rastrear e Sair” ou pressionando Ctrl+F8;

• Interromper – Para de executar o script.

4.3 A Caixa Objeto

A “Caixa Objeto” mostra o nome do objeto contendo o script que está rodando. Por exemplo, a Figura 2.12 mostra que o script corrente está anexado ao formulário “Main Topic”. Se você deseja ver o código anexado a quaisquer outros objetos, selecione os objetos específicos utilizando a caixa de combinação de objeto.

4.4 A Caixa Evento

A “Caixa Evento” mostra o nome do evento ao qual o script está anexado. Similar à “Caixa de Objeto”, você pode usar a caixa de combinação de Evento para examinar o código anexado a quaisquer eventos com o objeto corrente. A Figura 2.12 mostra que o código exibido está anexado ao evento QueryOpen.

4.5 A Janela de Depuração

A “Janela de Depuração” mostra o LotusScript que você está depurando. Uma seta aponta para a linha que está para ser executada.

4.6 A Caixa de Combinação Chamadas

A “Caixa de Combinação Chamadas” permite-lhe rastrear a rota que o seu script usou até a linha corrente. Toda vez que um sub ou função chama outro sub ou função, seu nome é adicionado à “Caixa de Combinação Chamadas” e é construído um histórico de chamadas. O subprograma que está sendo executado é mostrado no topo da lista.

4.7 A Paleta de Ponto de Interrupção

A “Paleta de Ponto de Interrupção” mostra quaisquer pontos de parada que você tem que definir. Você pode dar um duplo clique em um ponto de parada para que a linha seja mostrada na janela de Depuração. Veremos pontos de parada com maiores detalhes posteriormente.

4.8 A Paleta Variáveis

A Figura 2.13 mostra a “Paleta Variáveis”, uma das características mais úteis do depurador. Mostra as variáveis definidas e permite-lhe examinar e mudar o valor atual. A Paleta Variáveis mostra o nome da variável, seu valor atual e seu tipo. “Twisties” são mostrados próximos à variáveis que representam objetos ou complexas estruturas de dados. Você pode mudar o valor de uma variável digitando um novo valor dentro do campo “Novo valor”.

Figura 18.13

Click na Paleta de Variáveis para mostrar as variáveis do LotusScript.

4.9 A Paleta de Saída

A Paleta de Saída é usada para mostrar a saída de comandos de impressão de seu script.

4.10 Usando Pontos de Parada

Pontos de Parada são uma maneira de interromper a execução do script em uma linha específica. Quando o Script for interrompido, você poderá examinar o valor corrente das variáveis e propriedades. Você pode usar o depurador para fazer o seguinte:

• Definir ou limpar um ponto de parada simples – para definir um ponto de parada, dê um duplo clique na janela de depuração na linha que você deseja um ponto de parada. Uma sinal vermelho de parada aparece do lado esquerdo da linha para mostrar que aquele é um ponto de parada e o novo ponto de parada é adicionado à lista de pontos de parada mostrada na paleta “Ponto de Interrupção”;

• Limpar todos os pontos de parada – Para limpar um ponto de parada, dê um duplo clique na linha que o contém;

• Habilitar ou desabilitar temporariamente um ponto de parada simples – Para desabilitar temporariamente um ponto de parada, selecione-o na janela do depurador e selecione “Depurar – Desativar Ponto de Interrupção” na barra de menu do Notes. O sinal de parada muda para amarelo, indicando que o ponto de parada está desabilitado. Para reabilitá-lo selecione “Depurar - Ativar Ponto de Interrupção”;

• Habilitar ou desabilitar temporariamente todos os pontos de parada – Para desabilitar temporariamente todos os pontos de parada selecione “Depurar – Desativar Todos os Pontos de Interrupção” na barra de menu do Notes. Para reabilitá-los selecione “Depurar – Ativar Todos os Pontos de Interrupção”.

NOTA

Você pode também definir e limpar pontos de interrupção selecionando “Depurar - Definir/Limpar Ponto de Interrupção” através da barra de menu do Notes ou pressionando a tecla F9.

5 Técnicas Adicionais de Depuração

Você pode usar uma variedade de técnicas para testar seus scripts enquanto está usando o depurador.

5.1 Usando a caixa de Mensagem

Você pode testar seus scripts usando o comando de caixa de mensagem para mostrar mensagens de depuração. Simplesmente defina um sub que use a caixa de mensagem para mostrar textos que você fornece para indicar o progresso e o status de seu script que lhe informará o que está acontecendo. Então chame o sub quando você precisar mostrar informações do depurador. Um exemplo de sub de depuração é mostrado abaixo:

Sub ShowDebugMsg(strMsg As String)

Messagebox strMsg, MB_OK, “Debug Message”

End Sub

5.2 Usando a Função Print

Você pode também usar a função Print do LotusScript. Se você está testando um script que executa no cliente, Print escreve sua mensagem para a barra de status do Notes. Se o script estiver executando em um servidor, as mensagens são escritas para o banco de dados de log do servidor Notes. Quando você está depurando seu script a saída dos comandos Print como está mostrado na paleta de saída do depurador.

5.3 Usando um Controlador de Erros

Você pode desejar definir uma rotina de controle de erros para capturá-los, mostrar alguns detalhes sobre eles e continuar executando o script, porque quando o depurador detecta um erro, ele para de executar o script. Inclua o controlador em todas as rotinas de eventos de forma que todo erro seja detectado.

O LotusScript especifica um conjunto de erros padrão e um número correspondente de erros (como constantes), no arquivo LSERR.LSS, então lembre de usar “%Include” para incluir este arquivo no seu script se você deseja usar as constantes.

O modelo de controlador de erros mostrado abaixo, mostra uma caixa de mensagens para mostrar os detalhes do erro. Se um erro ocorrer em algum lugar no script o código após o “lblShowError” é executado, então o controle retorna para o comando seguinte ao que gerou o erro. Você pode facilmente modificar o código para escrever os detalhes do erro para um arquivo de log para uma gravação permanente de cada erro.

Sub Click(Source As Button)

‘ Set up the error handler

On Error Goto lblShowError

‘ Put your button code here ...

Exit Sub

lblShowError:

Messagebox “Line: “ & CStr(Erl) & “- “ & Error(Err), MB_OK,

“Error: “ & CStr(Err)

Resume Next

End Sub

6.0 Usando DLL

Com o LotusScript, você pode chamar funções e subrotinas em bibliotecas de funções internas tais como DLL. Você pode usar as características e funções do sistema de operação disponível à você através da sua interface de programação ou você pode chamar funções em suas próprias bibliotecas. Por exemplo, quando rodando no Windows 95 você pode usar o LotusScript para chamar funções externas de Linguagem C nas DLL’s do Windows 95. Você pode chamar funções externas em todas as plataformas seguintes:

• Windows 3.1;

• Windows 95;

• Windows NT;

• OS/2;

• UNIX;

• Macintosh

NOTA

As funções disponíveis e as convenções de chamada que você usa diferem de plataforma para plataforma. Se você deseja que o LotusScript rode em diferentes sistemas de operação, use a diretiva “%IF” para checar o tipo de plataforma na qual seu script esta rodando; então chame a função apropriada para aquela plataforma. Veja a documentação do LotusScript em %IF para detalhes.

Para chamar uma função em uma DLL externa, siga os passos seguintes:

1. Use o comando de declaração do LotusScript na seção de declaração do seu script para declarar a referencia à rotina como um sub ou como uma função;

2. Quando a rotina tiver sido declarada, chame-a como se fosse um sub ou uma função LotusScript.

Por exemplo, o script a seguir lhe mostra como declarar e usar a função externa GetFreeSystemResources. Esta função está disponível somente no Windows 3.1 e retorna a informação do sistema sobre como o Windows está administrando sua memória. Quando você roda o script em uma estação de trabalho Windows 3.1, ela mostra os recursos de sistemas disponíveis na barra de status do Notes.


Declare Function GetFreeSystemResources

Lib “User” (ByVal iFlag As Integer)

Dim iSystemResources As integer

Dim iGDIResources As Integer

Const GFSR_SYSTEMRESOURCES = 0

Const GFSR_GDIRESOURCES = 1

Const GFSR_GDIRESOURCES = 2

‘ Get the available Memory, GDI and User resources

iSystemResources = GetFreeSystemResources (GFSR_SYSTEMRESOURCES)

iGDIResources = GetFreeSystemResources (GFSR_GDIRESOURCES)

iUserResources = GetFreeSystemResources (GFSR_USERRESOURCES)

‘ Display them on the Notes status bar

Print “System Resources=” & Str$ (iSystemResources)

Print “GDI Resources =” & Str$(iGDIResources)

Print “User Resources =” & Str$(iUserResources)

End Sub

DICA

O LotusScript automaticamente converte para maiúsculo o nome da função, em um comando de declaração. No Windows 3.1 funciona muito bem; porém os nomes das funções usadas pelo Windows 95 e pelo Windows NT fazem distinção entre maiúsculo e minúsculo. Então se você chamar funções externas no Windows 95 e Windows NT, você deve sempre usar o “Alias” do comando de declaração para especificar o nome da função em maiúsculo ou minúsculo, conforme desejar.

Pelo padrão, argumentos são passados para funções externas por referência. Você pode refazer isto para certos tipos de dados e ter o argumento passado por valor usando a palavra chave “By Val. Por exemplo, as declarações a seguir passam ambos os argumentos por valor:

Declare Function iMax Lib “MYFUNCS” Alias “iMax

“(ByVal iX As Integer, ByVal iY As Integer) as Integer

7 Usando Evaluate e Execute

As funções Evaluate e Execute do LotusScript permitem-lhe compilar e executar funções do Notes e programas “on-the-fly” do LotusScript. Use Evaluate para calcular uma fórmula @function. Você fornece dois argumentos, a fórmula @function e o objeto usado para executar aquela formula. Por exemplo, você pode rodar a @function mostrada no próximo exemplo ao invés de um documento particular do Notes para mostrar o tamanho total para todos os arquivos anexados:


Const STR_FORMULA = “@if(@Attachments > 0; @Sum(@AttachmentLengths);0)”

Dim varTotalSize As Variant

Dim uiWorkspace As New Notes UIWorkspace

Dim uiDoc As NotesUIDocument

Dimdoc As NotesDocumet

Set uiDoc = uiWorkSpace.CurrentDocument

Set doc = uiDoc.Document

VarTotalSize = Evaluate(STR_FORMULA, doc)

Messagebox “Total size of all attached files is

“ & CStr (varTotalSize(0)) & “bytes.”

End Sub

NOTA

Você deve definir a fórmula para Evaluate quando o LotusScript é compilado, então você não pode usar a variável para definir a formula. No entanto, depois que estudarmos a função Executar estudaremos uma maneira de driblar o LotusScript de forma que você possa definir uma fórmula em tempo de execução para usar com “Avaliar”.

Usando a função Execute, você pode compilar e executar uma “string” de texto como um programa LotusScript. O LotusScript pega o conteúdo da “string”, compila e executa como um programa separado. Se você quiser passar dados entre seu programa principal e o programa criado pela função Execute, você pode declarar variáveis como Públicas. Desta forma, ambos os programas têm acesso às variáveis e podem usá-las para passar dados para trás e para frente entre eles. O exemplo seguinte usa um script separado para adicionar o número um à outro número.

Primeiro, na seção (Declarações) do script, declare uma variável Pública para passar o número para e a partir do script que está rodando pela função Execute:

Public piTempNumber As Integer

DICA

Como uma convenção, considere começar os nomes de variáveis Públicas com a letra p de forma que é fácil identificar que elas são públicas.

Então declare um sub para construir um mini-programa e chame Execute para executá-lo e mostrar os resultados:

Sub Increment (iNumber As Integer)

Dim strScript As String

PiTempNumber = iNumber

strScript = | piTempNumber = piTempNumber + 1 | ’ mini programa

Execute(strScript) ‘ executa o mini programa

Messagebox CStr(piTempNumber)

End Sub

Finalmente, crie um botão no formulário para chamar o novo sub:

Sub Click(Source As Buttom)

Dim i As Integer

i = 3

Increment i

End Sub

Quando você clicar no botão, o sub Incremente é chamado e o mini-programa (o qual adicionará “um” para o número fornecido) é compilado e executado.

Apesar deste ser um exemplo simples, ele demonstra como esta característica é poderosa. Você pode usar Execute para compilar e executar qualquer texto como um programa LotusScript. Por exemplo, você pode combinar Evaluate e Execute para evitar o problema de fornecer a fórmula para Evaluate como uma constante. Você precisará primeiro declarar uma variável Pública para conseguir o resultado da fórmula.

Public pvarResult As Variant

Então crie um sub que cria e executa um mini-programa usando a string fornecida como a fórmula:

Sub ExecuteFormula(strFormula As String, varResult As Variant)

Dim strScript As String

‘ Cria um mini-progama com a fórmula fornecida e adiciona o resultado a um a ‘variável pública que o programa principal possa usuá-la.

StrScript = | Const STR_FORMULA = “ | & strFormula & | “

Dim uiWorkspace As New notesUIWorkspace



Set uiDoc = uiWorkSpace.CurrentDocument


PvarResult = Evaluate (STR_FORMULA, doc)

‘ Executa o mini-programa

Execute (strScript)

‘ Salva o resultado retornado pela fórmula

varResult = pvarResult

End Sub

Para chamar um novo sub, adicione um botão à um formulário e use o seguinte script para passar a fórmula para o novo sub:

Sub Click (Source As Button)

Dim strFormula As String

Dim varResult As Variant

StrFormula = Inputbox$ (“Entre com uma fórmula Notes:”)

On Error Goto lblExecutionError

Call Execute Formula(strFormula, varResult)

Messagebox “O resultado do cálculo “&

StrFormula & “is “& CStr(varResult(0))

lblExit:

Exit Sub

lblExecutionError:

Messagebox “Não é possível calcular a fórmula para este documento.”

Resume lblExit

End Sub

Para testar o novo sub, siga os seguintes passos:

1. Clique no botão;

2. Digite a fórmula, do tipo @attachments, dentro da caixa de entrada e clique OK;

3. A caixa de mensagem aparece.

8 Extensões LotusScript

Extensões LotusScript ou LSX’s, são exatamente isto – extensões para o LotusScript. Um desenvolvedor de software ou um vendedor de ferramentas pode usá-los para adicionar classes extras ao Notes. Por exemplo, IBM produziu um conjunto de extensões LotusScript para Links de series MQ para Lotus Notes, que lhe permitem acessar transações e dados em outros sistemas. O Lotus tem usado LSX’s para adicionar três classes ao Notes que você pode usar para acessar fontes de dados ODBC.

NOTA

Para mais informações sobre Links de series MQ para Lotus Notes leve o seu cliente Web para http://www.hurslev.ibm.com/mqseries.

Para usar uma extensão LotusScript, inclua o comando “UseLSX” na parte (Options) da seção (Global) de um script. Por exemplo, para usar o ODBC LotusScript, adicione a linha seguinte para a parte (Option):

UseLSX “*LSXOBC”

O comando carrega DLL que contém as três classes que formam extensões ODBC para o LotusScript.

CAPÍTULO 3 – CLASSES E OBJETOS NOTES

• A diferença entre classes “front-end”e “back-end”;

• As 25 classes de objetos Lotus Notes;

• Como usar as propriedades e métodos de cada classe em seus programas LotusScript.

Em capítulos anteriores, você aprendeu o básico sobre a linguagem Lotus Notes, as ferramentas necessárias para começar a construir programas simples no LotusScript. Neste capítulo, veremos as classes de Objetos Lotus Notes e como você pode usá-los para construir aplicações Notes mais sofisticadas que exploram ao máximo o potencial tanto do Notes como do LotusScript. A chave para construir essas aplicações é um bom entendimento das classes de Objeto Lotus Notes.

Entendo as Classes de Objetos Lotus Notes

As classes de Objetos Lotus Notes permitem a você usar o LotusScript para acessar bancos de dados, visões, documentos e itens. Por exemplo, a partir de programas LotusScript, você pode usar as classes de objeto do Notes para criar, abrir ou excluir bancos de dados e adicionar, modificar ou deletar documentos nesses bancos. Neste capítulo veremos detalhadamente cada uma dessas classes e veremos como cada uma pode ser usada da melhor forma no LotusScript. Mas, antes disso, precisamos diferenciar os tipos de classes.

Existem dois tipos de classes que permitem-lhe trabalhar com objetos Notes: front-end ou interface do Usuário (UI) e back-end.

NOTA

Os dois tipos de classes que veremos neste capítulo não são as únicas classes disponíveis no LotusScript. Outros tipos de classes podem ser adicionadas como extensões do LotusScript do tipo “Open Database Connectivity (ODBC)” , que veremos ainda neste capítulo.

As classes UI permitem-lhe trabalhar com bancos de dados, visões e documentos que são mostrados na janela ativa do Notes. Por exemplo, você pode trabalhar com o documento que está atualmente na tela usando a classe NotesUIDocument. Os métodos e propriedades das classes UI permitem-lhe trabalhar com visões e documentos da mesma maneira que o usuário pode. Você pode digitar textos nos campos, mover o cursor, usar a área de transferência e atualizar visões.

Existem 4 classes UI que representam:

• “Workspace” do Notes

• Documento corrente

• A visão corrente

• Banco de dados corrente

Abordaremos essas classes primeiro quando estudarmos classes em detalhes.O segundo tipo de classe, as classes Back-End, representam as partes

componentes do Notes. Elas incluem alguns elementos óbvios do tipo banco de dados, visões, documentos, campos e mais alguns objetos abstratos do tipo seções e coleções de documentos.

Você necessita entender a diferença entre os dois tipos de classes principalmente porque elas são interligadas. Por exemplo, um documento mostrado na tela tem duas representações diferentes: O documento UI e o documento back-end. Quando você digita dados no documento UI, o documento back-end correspondente não é atualizado até você salvar suas mudanças. Ao contrário, se um agente atualizar a parte back-end de um documento, o documento UI não mostra as mudanças até que ele seja atualizado. Veremos alguns métodos que se pode usar para manter ambos os documentos atualizados.

O restante do capítulo mostra cada classe em detalhes. Vamos começar pelo espaço de trabalho do Notes, vendo primeiramente a classe NotesUIWorkspace.

1 NotesUIWorkspace

A Classe NotesUIWorkspace representa a janela corrente de espaço de trabalho do Notes. Ela permite-lhe usar o LotusScript para realizar algumas das ações que você normalmente realiza a partir do área de trabalho do Notes, tais como abrir bancos de dados ou criar e editar documentos. Se um documento já está sendo mostrado em uma janela ativa ou sublinhado em uma visão, você pode usar esta classe para trabalhar com o documento.

A Classe tem somente uma propriedade, CurrentDocument, o qual você usa para chamar o documento corrente. De posse do documento, você tipicamente usa as propriedades e métodos da classe NotesUIDocument para trabalhar com o mesmo. Por exemplo, o script a seguir acha o documento corrente e mostra o valor de um campo chamado title na caixa de mensagem:

Dim uiWorkspace As New NotesUIWorkspace


Set uiDoc = uiWorkspace.CurrentDocument

MessageBox(uiDoc.FieldGetText(“Title”))

A classe NotesUIWorkspace possui dez métodos que lhe permitem abrir bancos de dados e URLs, criar e editar documentos, checar alarmes e atualizar visões. Você adiciona um banco de dados à sua área de trabalho usando o método AddDatabase. Você abastece o servidor e o nome do arquivo para o banco de dados e isto é adicionado para a paleta corrente de área de trabalho. Você abre um banco de dados usando o método OpenDatabase, do LotusScript equivalente ao comando FileOpenDatabase. Se você comparar o método OpenDatabase com o comando FileOpenDatabase, você verá que seus parâmetros são muito similares. O método FileOpenDatabase aceita até 6 parâmetros. Os primeiros dois parâmetros especificam o servidor e o nome do arquivo do banco de dados a

ser aberto e os parâmetros restantes para especificar como abrir o banco de dados. Você pode abrir o banco de dados de uma visão ou de um navegador específico.

Por exemplo, você pode fornecer o nome ou “alias” de uma visão como o terceiro parâmetro para abrir o banco de dados naquela visão. Se a primeira coluna na visão é classificada, você pode fornecer uma chave como quarto parâmetros. Neste caso o banco de dados é aberto na visão que você especificou e o primeiro documento correspondente à chave é sublinhado. Você pode também usar o terceiro e o quarto parâmetros para abrir um navegador. Você fornece o nome do navegador como terceiro parâmetro e “True” ou “False” como quarto parâmetro para indicar se o navegador deve ou não ser aberto na sua própria janela. O quinto parâmetro especifica se a visão ou navegador estão abertos em uma janela, mesmo que já exista uma janela aberta que contenha a visão ou navegador. Especifique “True” para ter uma nova janela aberta, ou “False” para usar uma janela existente. O último parâmetro é usado para indicar se o banco de dados deve ser aberto sem adicioná-lo à sua área de trabalho. Especifique “True” para abrir o banco de dados temporariamente ou “False” para adicionar o banco de dados à sua área de trabalho.

Então abra um banco de dados usando um botão, use o LotusScript a seguir:



Call uiWorspace.OpenDatabase(“Emerald”, “Sales\Quota.nsf”, “Weekly Totals”,

“Northern”, True, False)

End Sub

Isto abre um banco de dados “QUOTA.NSF” no diretório VENDAS no servidor Esmeralda na visão Totais Semanais e seleciona o documento totais de vendas da região Norte. Os dois últimos parâmetros asseguram que uma nova janela será aberta para a visão e que o banco de dados será sempre adicionado à área de trabalho do usuário.

Você pode também usar o método FileOpenDatabase para abrir um navegador. Ao invés do nome da visão você fornece o nome do navegador e ao invés de uma chave você fornece “True” ou “False” para especificar se o navegador deve abrir sua própria janela. Os outros parâmetros são os mesmos usados para abrir uma visão. Por exemplo, o script a seguir abre um navegador chamado “Main Navigator” (navegador principal) na sua própria janela.



Call uiWorspace.OpenDatabase(“Emarald”, “Sales\Quota.nsf”, “Weekly Totals”,

“Main Navigator”, True, True, False)

End Sub

Após ter selecionado um documento em uma visão, você pode abrí-lo usando o método EditDocument. Então, para o botão abra o documento totais de vendas do Norte no modo de edição, use o seguinte script atualizado:




Call uiWorspace.OpenDatabase(“Emerald”, “Sales\Quota.nsf”, “Weekly Totals”,

“Northern”, True, True)

Set uiDoc = uiWorkspace.EditDocument(true)

End Sub

Para abrir o documento no modo de leitura, especifique “False” como o parâmetro para o EditDocument.

Você pode criar novos documentos em um banco de dados usando o método de ComposeDocument. Por exemplo, o script a seguir cria um documento de totais de vendas para a região Leste sempre que o botão é clicado:




Set uiDoc = uiWorkspace.ComposeDocument( “Emerald”, “Sales\Quota.nsf”,

“Sales Totals”)

Call uiDoc.FieldSetText(“Region”, “Eastern”)

End Sub

Um novo método que surgiu na versão 4.5 é EditProfile. Você pode usá-lo para criar ou editar um documento de perfil escondido no banco de dados corrente. Um documento de profile permite-lhe armazenar e atualizar informações específicas no banco de dados. Você abre uma página WWW (Word Wide Web) usando o método URLOpen. Você pode especificar o URL juntamente com alguns parâmetros que especificam se achar a última cópia da página da Web. Como alternativa, se não fornecer nenhum parâmetro, o URLOpen mostra a caixa de diálogo URL Open para você dar entrada no URL que deseja abrir.

EnableAlarms e CheckAlarms permite-lhe usar a característica de alarme do calendário que acompanha o Lotus Notes. EnableAlarms inicia o processo que monitora alarmes. Então após este processo estar rodando , CheckAlarm permite-lhe checar se algum alarme está na fila.

Você pode usar o método DialogBox para realmente incrementar suas interfaces de usuários. Ela mostra o documento corrente em uma caixa de diálogo usando o formulário que você especificar. Isto é realmente muito útil quando o formulário contém uma região de layout único, porque neste caso o formulário comporta-se justamente como uma caixa de diálogo padrão. Você preenche os campos e pressiona “OK” ou “Cancel” quando terminar. A melhor parte é que se o formulário que você especificar tiver algum nome de campo em comum com o documento corrente, o conteúdo daqueles campos são mostrados na caixa de diálogo. Se o usuário mudar o conteúdo de qualquer um dos campos e clicar OK, o campo correspondente no corrente documento será atualizado.

Para ver um bom exemplo de como um formulário é mostrado em uma caixa de diálogo, crie um novo “memo” no Correio de seu banco de dados e clique no botão de Opções de Entrega. O Formulário Opções de Entrega é mostrado na caixa de diálogo e qualquer valor que você der entrada será atualizado no “Memo”quando você clicar OK.

O último método na classe NotesUIWorkspace é ViewRefresh. Você usa o ViewRefresh para atualizar ou a visão que está sendo mostrada ou, se um documento está sendo mostrado, a visão a partir da qual o documento foi selecionado. Atualizar um documento que está sendo mostrado é muito simples, simplesmente chame ViewRefresh e o documento está atualizado. As coisas tornam-se um pouco mais complicadas quando você deseja atualizar uma visão de um documento recentemente criado porque você precisa primeiro atualizar a visão “back-end”, usando o método de Refresh da classe do NotesView, de forma que o novo documento é incluído na visão. Então você precisa atualizar a visão “front-end” usando o método NotesUIWorkspace ViewRefresh de forma que a visão atualizada seja mostrada.

Tabela 3.1 mostra todas as propriedades do NotesUIWorkspace e a tabela 3.2 lista os métodos. Tabela 3.1 Propriedades da classe NotesUIWorkspace

Propriedade Descrição Tipo de Dados UsoCurrentDocument O documento que está sendo

mostradoNotesUIDocument Leitura

Tabela 3.2 Método da classe NotesUIWorkspace

Método Descrição Tipo de Dados Retornados

Valor Retornado

AddDatabase Adicione um novo banco de dados à área de trabalho

Nenhum Nenhum

CheckAlarms Checar novos alarmes no correio do banco de dados

Nenhum Nenhum

ComposeDocument

Crie um novo UI Documente em um Banco de Dados específico usando um formulário específico e mostrando-o no modo de edição.

Notes Documento UI

O Novo UIDocumento

DialogBox Mostre uma caixa de diálogo com botões “OK” e “Cancel” que contém o documento corrente exibido usando um formulário que você especifica.

Boolean Verdadeiro se o usuário seleciona “OK” na caixa de diálogo

EditDocument Verdadeiro para abrir o documento corrente no modo de edição. Falso para abrí-lo no modo de leitura.

Documento UI O documento UI recentemente aberto

EditProfile Crie um novo documento de perfil ou abra uma perfil existente.

Nenhum Nenhum

EnableAlarms Defina com verdadeiro (True) para iniciar o processo em background que checa alarmes.

Boolean Verdadeiro se o processo for permitido

OpenDatabase Abra um Banco de Dados em uma visão específica e opcionalmente sublinhe um documento específico

Nenhum Nenhum

URLOpen Abra um URL Nenhum Nenhum

ViewRefresh Atualizar a visão de um documento Nenhum Nenhum

2 NotesUIDocument

A classe NotesUIDocument permite-lhe trabalhar com o documento ativo, isto é, o documento que está aberto na sua área de trabalho ou sublinhado em uma visão. Você usa esta classe para fazer o seguinte:

• Atualizar o conteúdo dos campos em um documento;

• Posicionar o cursor dentro de um documento;

• Criar e manipular documentos;

• Mudar a forma que um documento é mostrado;

• Enviar, passar para frente ou excluir um documento.

Veremos essas opções detalhadamente. A tabela 3.3 lista todas as propriedades da classe NotesUIDocument e a Tabela 3.4 lista os métodos.

Tabela 3.3 Propriedades da classe NotesUIDocument

Propriedade Descrição Tipo de dados UsoAutoReload Selecione Verdadeiro para atualizar

automaticamente o documento exibido para refletir quaisquer mudanças que tenham sido feitas para seu documento back-end associado. Leia para checar as posições atuais. Use-o no evento Postopen.

Boolean LeituraEscrita

CurrentField O nome do campo aonde o cursor se encontra

String Leitura

Document O documento back-end associado com o documento UI corrente

Documento Notes

Leitura

EditMode Defina como Verdadeiro(true) para colocar o documento UI atual no modo de edição ou leia para checar se o documento UI atual está no modo de edição

Boolean Leitura Escrita

FieldHelp Defina como Verdadeiro(true), quando o documento UI estiver em modo de edição, para mostrar o campo de ajuda. Leia para checar se o campo de ajuda está sendo exibido.


HiddenChars Defina como Verdadeiro(true), quando o documento UI estiver em modo de edição, para mostrar os caracteres de formatação ocultos. Leia para checar as posições atuais.


HorzScrollBar Defina com Verdadeiro(True) para mostrar a barra de rolagem horizontal. Leia para checar se a mesma está sendo mostrada.


InPreviewPane Verdadeiro(True) se o documento está Boolean Leitura

sendo mostrado na janela de previsualização

IsNewDoc Verdadeiro(True) se o documento nunca tiver sido salvo

Boolean Leitura

PreviewDocLinks Defina com Verdadeiro(True) para mostrar a janela de previsualização para um link. Leia para checar se a mesma está sendo exibida.


PreviewParent Defina Verdadeiro(True) para mostrar o “Pai” do documento UI atual na janela de previsualização. Leia para checar se a janela de previsualização está sendo mostrada.


Ruler Defina Verdadeiro(True) para mostrar a régua. Leia para checar se a mesma está sendo exibida.


WindowTitle O título da janela para o documento que está sendo mostrado.

String Leitura

Tabela 3.4 Métodos do NotesUIDocument


Valor Retornado

Categorize Coloca o documento dentro de uma categoria

Nenhum Nenhum

Clear Somente no modo de edição, exclui texto, gráficos ou objetos que estão selecionados.

Nenhum Nenhum

Close Fecha o documento UI atual. Nenhum NenhumCollapsAll Sections

Contrai todas as seções no atual documento UI aberto.

Nenhum Nenhum

Copy Copia texto, gráficos ou objetos selecionados para a área de transferência

Nenhum Nenhum

CreateObject Para um documento UI no modo de edição com o cursor em um campo de texto rico cria um OLE ou um objeto ActiveX.

Variante UM “handle” para um objeto criado recentemente

Cut Somente no modo de edição, corta o texto, gráficos ou objeto selecionado no documento e coloca-os na área de transferência.

Nenhum Nenhum

DeleteDocument Somente no modo de leitura, marca o documento para exclusão e fecha-o

Nenhum Nenhum

DeselectAll “Deseleciona” qualquer texto, gráfico ou objeto selecionados.

Nenhum Nenhum

ExpandAll Sections

Expande todas as seções no documento UI aberto atualmente.

Nenhum Nenhum

FieldAppendText Adiciona o texto fornecido ao conteúdo de um campo (ou o campo corrente se não for fornecido nenhum nome)

Nenhum Nenhum

FieldClear Somente no modo de edição, limpa o conteúdo de um campo (ou o campo corrente se não for fornecido nenhum nome)

Nenhum Nenhum

FieldContains Verdadeiro(True) se um campo (ou o campo corrente se não for fornecido nenhum nome) contém um texto específico.

Boolean Verdadeiro se o campo com-tém o texto que você especificou

FieldGetText Pega o conteúdo de um campo (ou o campo corrente se não for fornecido nenhum nome). Converte o conteúdo em uma string de texto.

String O conteúdo do campo convertido em um texto

FieldSetText Somente no modo de edição, define o conteúdo de um campo (ou o campo corrente se não for fornecido nenhum nome) para o valor fornecido. Converte automaticamente o valor fornecido para o tipo correto para o campo.

Nenhum Nenhum

FindFreeTime Dialog

Mostra a caixa de diálogo “Tempo Livre” Nenhum Nenhum

Foward Crie um correio Memo contendo o documento UI aberto atualmente

Nenhum Nenhum

GetObject Dando o nome de um OLE ou objeto ActiveX, retorna um “Handle” para um objeto encontrado

Variante Um “handle” para o objeto

GoToBottom Somente no modo de edição, coloca o cursor no último campo editado

Nenhum Nenhum

GoToField Somente no modo de edição, coloca o cursor no campo determinado

Nenhum Nenhum

GotoNextField Somente no modo de edição, coloca o cursor no próximo campo editável abaixo e à direita da posição atual do cursor.

Nenhum Nenhum

GoPrevField Somente no modo de edição, coloca o cursor no próximo campo editável acima e à esquerda da posição atual do cursor.

Nenhum Nenhum

GotoTop Somente no modo de edição, coloca o cursor no primeiro campo editável

Nenhum Nenhum

InsertText Somente no modo de edição, insera o texto fornecido na posição onde o cursor se encontra

Nenhum Nenhum

Paste Somente no modo de edição, cola o conteúdo da área de transferência na posição atual do cursor.

Nenhum Nenhum

Print Imprime o documento atual. Opcionalmente mostra a caixa de diálogo “File Print”

Nenhum Nenhum

Refresh Somente no modo de edição, computa todas as fórmulas para os campos computados no documento

Nenhum Nenhum

RefreshHideFormulas

Computa todas as fórmulas ocultas em um documento

Nenhum Nenhum

Reload No modo de edição, atualiza o documento Nenhum Nenhum

UI com qualquer mudança que tenha sido feita ao documento back-end associado

Save Somente no modo de edição, salva o documento

Nenhum Nenhum

SaveNewVersion Somente no modo de edição, salva o documento como uma nova versão (o formulário do documento fornecido tem disponíveis as opções de versões apropriadas

Nenhum Nenhum

SelectAll Somente no modo de edição, seleciona o conteúdo do campo atual. No modo de leitura, seleciona o conteúdo do documento inteiro

Nenhum Nenhum

Send Envia o documento Nenhum Nenhum

2.1 Atualizando campos

A classe do NotesUIDocument permite-lhe acessar os dados armazenados nos campos com um documento. Dependendo do que você deseja, existem dois grupos de métodos que você pode usar, aqueles que começam com Field e aqueles que começam com Goto. Os métodos de Field são mais usáveis quando você precisa se referir à um campo pelo nome. Se você sabe a posição do campo no documento ou se você deseja mover o cursor dentro do documento, use os métodos de Goto.

Veremos os métodos de Field primeiro. Existem cinco deles e cada um espera que você forneça um nome de campo como seu primeiro parâmetro. Um ponto positivo é que se você fornece um nome de campo vazio, o método assume que você está se referindo ao campo atual. Você pode achar o nome do campo atual perguntando a propriedade CurrentField. Depois que você tiver identificado um campo, você pode pegar seu conteúdo usando o método FieldGetText. Isto retorna o conteúdo do campo que você especificar, convertido em uma string de texto. Se você deseja mudar o conteúdo de um campo use FieldSetText, FieldAppendText ou FieldClear. FieldSetText altera o conteúdo atual do campo com o texto que você fornece. FieldAppendText é similar, mas ele adiciona o novo valor ao valor atual do campo. FieldClear exclui o conteúdo do campo. Se você precisa checar se um campo contém um determinado valor, use FieldContains. Você fornece o nome do campo e um valor e o método informa Verdadeiro se o valor ocorrer em algum lugar dentro do campo. Por exemplo, quando adicionado ao evento QuerySave de um formulário contendo dois campos de texto editáveis, Texto e Prioridade, o script seguinte checa se o campo Título contém a palavra Urgente e se tiver coloca a prioridade do campo para Alta:

Sub QuerySave(Source As Notessuidocument, Continue As Variant)

If source.FieldContains(“Título”,”Urgente”) Then Call source.FieldSetText(“Prioridade”, “Alta”)

End If

End Sub

A outra maneira de trabalhar com campos é mover o cursor para dentro de um campo e trabalhar com seu conteúdo. Existem cinco métodos que lhe permitem fazer isto.

Se você sabe o nome do campo aonde você deseja colocar o cursor, use o método GotoField. Você fornece o nome do campo e o método coloca o cursor naquele campo. GotoTop move o cursor para o primeiro campo editável no documento, GotoBottom coloca o cursor no último campo editável. Se você deseja navegar através dos campos de um documento use GotoNextField e use GotoPrevField para mover o cursor de campo para campo.

DICA

O documento deve estar no modo de edição para que estes métodos funcionem.

Após o cursor estar em um campo, você pode usar quaisquer dos métodos de Field com um nome de campo vazio para trabalhar com o conteúdo do campo. Alternativamente, você pode usar InsertText ou uma combinação dos métodos SelectAll e dos métodos de área de transferência Cut, Copy, Paste e Clear.

Use InsertText para adicionar algum texto dentro de um campo na posição atual do cursor. Para copiar o conteúdo do campo corrente para a área de transferência, use SelectAll para sublinhar o conteúdo do campo, então use Cut ou Copy para copiar o conteúdo para a área de transferência. Após você algum dado na área de transferência, você pode usar Paste para colar o dado da área de transferência dentro de um campo. Se você deseja deletar o conteúdo do campo, use o método Clear.

O seguinte botão de script, quando executado em um formulário contendo dois campos, Título e História, seleciona e copia o conteúdo do primeiro campo editável, Título, para o campo História e então anexe os dados atuais para o campo Histórico. Assegure-se que você dá entrada em algum texto dentro do campo Título, caso contrário não haverá nada para selecionar e você obterá um erro.





Call uiDoc.GotoTop

Call uiDoc.SelectAll

Call uiDoc.Copy

Call uiDoc.GotoField( “História”)

Call uiDoc.Paste

Call uiDoc.InsertText( “ “ & Date$)

End Sub

2.2 Trabalhando com Objetos

Uma poderosa característica da classe NotesUIDocument é sua capacidade para trabalhar com objetos OLE. Quando um documento está no modo de edição com o cursor em um campo de texto rico, você pode usar o método CreateObject para criar e inserir um novo objeto OLE. Se você não fornecer nenhum parâmetro para o método, o Notes mostra uma caixa de diálogo “Create Object” e você pode escolher o tipo de objeto para criar a partir da lista. Alternativamente, você pode fornecer parâmetros para definir o tipo de objeto para criar. O primeiro parâmetro é o nome do novo objeto. Você pode usar este nome mais tarde para referir-se ao objeto dentro de um script. Então, dependendo do tipo de objeto que você deseja criar, você especifica o tipo do objeto ou o caminho para um arquivo que contenha o objeto.

Por exemplo, para criar automaticamente um novo Componente do “Lotus Project Scheduler” sempre que um novo documento for criado, use o seguinte:

Sub PostOpen(source As NotesUIDocument)

Dim objNewSchedule As Variant

If source.IsNewDoc Then

Set objNewSchedule = source.CreateObject(“Project Schedule”,

“Lotus.Project.1”)

End If

End Sub

Isto automaticamente cria o novo componente de agenda no primeiro campo de texto rico no documento.

Para criar um objeto “Excel Spreadsheet” a partir de um arquivo existente, em um campo de texto rico chamado “Sheet” em um documento aberto, use o seguinte script de botão:





Call uiDoc.GotoField(“Sheet”)

Call uiDoc.CreateObject(“Expenses”,””, “C:\EXPENSES.XLS”)

End Sub

NOTA

Com o “CreateObject”, você fornece o tipo de objeto ou o nome do arquivo e não ambos.

Se um documento contém um objeto, você pode pegar o “handle” do OLE para o objeto OLE usando o método GetObject. Você fornece o nome do objeto e o método retorna o Handle para ele ou “Nothing” se não conseguir achar o objeto.

Por exemplo, para pegar o handle para o “Excel Spreadsheet” criado no último exemplo, use o seguinte:



Dim objSheet As Variant

Set uiDoc = uiWorspace.CurrentDocument

Set objSheet = uiDoc.GetObject( “Expenses”)

2.3 Mudando a forma que o documento é mostrado

Existe um número de propriedades que você pode definir para mudar a forma como o documento é mostrado. Você pode tornar o help de campo ativo ou não usando a propriedade FieldHelp. Defina a propriedade Ruler para mostrar ou esconder a régua e o HorzScrollBar para adicionar ou remover a barra de rolagem na área inferior do documento. Quando você precisar mostrar ou esconder a janela de pre-visualização, você pode usar o PreviewDocLink ou o PreviewParentDoc, conforme seja apropriado. Você pode checar se o documento está sendo mostrado na janela de preview checando sua propriedade InPreviewPane.

NOTA

A propriedade PreviewParent tem um comando(@Command) correspondente, ShowHideParentPreview que permite-lhe mostrar e esconder a janela de preview.

Se você precisar mudar o documento do modo de leitura para edição ou vice-versa, defina a propriedade EditMode. Após o documento estar no modo de edição, você pode usar a propriedade HiddenChars para que os campos mostrem seus caracteres formatados.

Você pode também definir o título que o Notes mostra para o documento que está usando a propriedade WindowTitle.

Várias propriedades e métodos do NotesUIDocument estão de acordo com como e quando o documento é atualizado. A propriedade AutoReload é usada para assegurar que o documento mostrado será atualizado sempre que seu documento back-end mudar. O default para AutoReload é verdadeiro, então a menos que você mude-o, seu documento estará sempre atualizado de acordo com o seu back-end. Se você definir AutoReload para Falso, você precisa usar o método Reload para atualizar o documento mostrado para incluir quaisquer mudanças que tenham sido feitas para o seu documento back-end.

NOTA

Reload não atualiza a aparência de quaisquer itens de texto rico que foram mudados em seu documento back-end até que você feche e abra novamente o documento.

O método Refresh recalcula todos os componentes dos campos computados, exatamente como se você tivesse pressionado F9. O método RefreshHideFormulas recalcula todas as fórmulas ocultas para o corrente documento. Você realmente usa RefreshHideFormulas quando um valor mudou no documento de forma a afetar sua apresentação. Por exemplo, você pode desejar exibir ou ocultar uma seção dentro de um documento dependendo do valor de um campo. Quando o valor daquele campo muda, chame RefreshHideFormulas para assegurar que a seção está sendo exibida ou ocultada, conforme desejar.

Enquanto estivermos no assunto de seções, você pode mudar a maneira que todas as seções dentro do documento atual são mostradas usando os métodos CollapseAllSections e ExpandAllSections.

2.4 Trabalhando com o Documento

Após ter um documento aberto na sua frente, o você pode fazer com ele? Para começar, você pode checar se é um documento novo ou não usando a propriedade IsNewDoc. A propriedade retorna verdadeiro(true) se o documento nunca tiver sido salvo em disco. Você pode imprimir o documento usando o método Print. Você pode levar o Notes a mostrar a caixa de diálogo “FilePrint” chamando o método sem parâmetros. Alternativamente você pode fornecer parâmetros para o número de cópias a serem impressas, as páginas de início e fim e se é para imprimir em modo rascunho. Se você usar esses parâmetros, o Notes imprime seu documento sem mostrar a caixa de diálogo “FilePrint”.

Você pode categorizar o documento usando Categorize. Você fornece o nome de uma categoria e o método coloca o documento naquela categoria. Se o documento tem permissão para ser enviado, isto é, contém um campo “SendTo”, você pode usar Send para enviá-lo para a lista de destinatários no campo “SendTo”. Se o documento contém um campo “CopyTo” ou “BlindCopyTo”, os nomes contidos nesses campos também receberão uma cópia do documento. Você pode passar adiante a cópia do documento usando o método Foward. Foward cria um novo memo de correio contendo o documento e você completa e envia o memo como você faria com qualquer outro memo de correiro.

Após você concluir o documento, você pode fechá-lo chamando o método Close. Se você tiver feito quaisquer mudanças no documento, o Notes pergunta se você gostaria de salvar suas mudanças. Se você realmente concluiu o documento, certifique-se de que o documento está no modo de leitura, você pode excluí-lo usando o método DeleteDocument. Este método fecha o documento e marca-o para exclusão, da mesma maneira que você marca documentos para exclusão em visões. O documento só é excluído quando você atualiza a visão ou sai do banco de dados e escolhe para excluir documentos marcados.

2.5 Salvando Suas Mudanças

Após terminar mudanças em um documento existem três métodos que permitem-lhe salvar suas mudanças. Estes métodos salvam o documento para um disco exatamente da mesma maneira que escolhendo “File\ Save” no menu. O método SaveNewVersion salva

uma nova versão do documento. Para que ele funcione, o formulário do documento deve ter as seguintes especificações:

• Para salvar o formulário com versões as especificações devem ser as seguintes: Novas versões tornam-se respostas Versões anteriores tornam-se respostas Novas versões tornam-se irmãs

• As versões devem ser criadas manualmente, isto é, a especificação Criar Versões deve ser Manual-Arquivo, Nova versão.

Se ambas as condições se encontrarem, SaveNewVersion cria uma nova versão do tipo apropriado.

3 NotesView

A classe NotesUIView representa a visão exibida atualmente. Não existem métodos associados com a classe. Suas três propriedades estão mostradas na tabela 3.5.

Tabela 3.5 Propriedades da classe NotesUIView

Propriedade Descrição Tipo de Dados UsoCalendarDateTime Somente aplicável em visões de

calendário. A data e a hora da área selecionada.

String Leitura

Documents Uma coleção de todos os documentos na visão atual.

NotesDocumentCollection

Leitura

View A visão back-end que corresponde à visão atual

NotesView Leitura

CalendarDateTime retorna uma string contendo a data e a hora associadas com a área que está selecionada atualmente na visão calendário. A propriedade Documents retorna um objeto NotesDocumentCollection que contém todos os documentos na visão. Você usa a propriedade View para acessar o objeto NotesView back-end que corresponde à visão com a qual você está trabalhando.

4 NotesUIDatabase

A classe NotesUIDatabase representa o banco de dados Notes que está aberto atualmente. Suas duas propriedades e um método estão mostrados nas tabelas 3.6 e 3.7.

Tabela 3.6 Propriedades da classe NotesUIDatabase

Propriedade Descrição Tipo de Dados UsoDatabase O banco de dados back-end que

corresponde ao banco de dados atualNotesDatabase Somente

leituraDocuments Uma coleção de todos os documentos no NotesDocument Somente

banco de dados. Collection leitura

Tabela 3.7 Métodos da classe NotesUIDatabase

Propriedade Descrição Tipo de Dado de retorno

Valor de Retornado

OpenView Dado o nome de uma visão no banco de dados atual, abre a visão

Nenhum Nenhum

As propriedades Documents e DataBase permitem-lhe acessar alguns dos objetos back-end que correspondem ao banco de dados atual. OpenView permite-lhe abrir uma visão no Banco de Dados.

5 NotesSesion

A classe NotesSession é a principal de todas as classes back-end e representa o ambiente do script atual.

Você pode usar classe NotesSession para responder as questões seguintes sobre o script atual:

Em que banco de dados o script está rodando?

• O script está rodando em um servidor Notes ou em uma estação de trabalho?

• Se rodando em um servidor, qual o nome do servidor?

• Se rodando em uma estação de trabalho, quem é o usuário atual?

• Em qual versão do Notes o script está rodando?

• Em que plataforma ele está rodando?

• Para agentes, quando foi a última rodada do agente, o que aconteceu e algum arquivo foi salvo?

A tabela 3.8 lista todas as propriedades da classe NotesSession e a Tabela 3.9 mostra seus métodos. Você pode usar métodos NotesSession para fazer o seguinte:

• Ler e escrever em variáveis de ambiente no arquivo NOTES.INI;

• Abrir bancos de dados;

• Criar outros objetos Notes do tipo NotesDataTime, NotesLog, NotesNewsletter e NotesDBDirectory;

• Marcar documentos como tendo sido processados por um agente.

Tabela 3.8 Propriedades da classe NotesSession

Propriedade Descrição Tipo de Dados UsoAddressBooks O livro de endereços que estão disponíveis ao

script atual.Array of NotesDatabases

Leitura

CommonUserName A parte do nome comum da pessoa ou servidor rodando o script

String Leitura

CurrentAgent O agente, se existir, que está rodando atualmente

NotesAgent Leitura

Current Database O banco de dados no qual o script está localizado.

Notes Database Leitura

DocumentContext Para agentes que tenham sido iniciados via Notes API e tenha criado um documento, esta propriedade retorna o documento back-end criado recentemente.

Notes Document Leitura

EffectiveUserName Se em uma Estação de Trabalho, o nome completo da pessoa que está rodando o script. Se em um servidor, o nome completo da pessoa que editou por último o script.

String Leitura

International As especificações internacionais da máquina na qual o script está rodando.

NotesInternational Leitura

IsOnServer Verdadeiro se o script está rodando em um servidor. Falso, se o script está rodando em uma estação de trabalho.

Boolean Leitura

LastExitStatus O código de status de saída retornado pelo gerenciador de agentes na sua última execução

Integer Leitura

LastRun Somente para agentes script. A data quando o agente rodou pela última vez.

Variante do tipo DATA

Leitura

NotesVersion A versão do Notes na qual o script está rodando

String Leitura

Platform O tipo de sistema de operação no qual o script está rodando

String Leitura

SavedData Somente para agentes script. Um documento Notes guardado dentro do Banco de Dados que pode ser usado para armazenar dados entre execuções do agente.

Documento Notes Leitura

UserName Se em uma Estação de Trabalho, o nome comum da pessoa que está rodando o script, Se em um Servidor, o nome comum da pessoa que editou o script por último.

String Leitura

Tabela 3.9 Métodos da classe NotesSession

Propriedade Descrição Tipo de Dado de retorno

Valor de Retornado

CreateDate Cria um novo objeto NotesDateRange Notes DataRange

O objeto NotesDataRange criado recentemente

Close Fecha a seção atual Nenhum Nenhum

CreateDataTime Dada uma string representando data e NotesDataTime O objeto Notes

hora válidas, cria um novo objeto NotesDateTime

DataTime criado recentemente

CreateLog Dada uma string usada para dar nome ao Log, cria um novo objeto NotesLog

NotesLog O objeto Notes Log criado recentemente

CreateNewsLetter

Dado um objeto NotesDocument Collection, cria um novo objeto NotesNewsletter

NotesNewsletter O objeto Notes Newsletter criado recentemente

CreateTimer Cria um novo objeto NotesTimer NotesTimer O objeto Notes Timer criado recentemente

FreeTimeSearch

Procura tempos livres para fazer calendários e listas

Array de NotesDateRange

Uma variedade de objetos NotesDataRange representando vagas (slots) disponíveis

GetDatabase Dado o servidor e nome de arquivo para um banco de dados, cria um novo objeto NotesDatabase que pode ser usado para acessar o banco de dados e, se possível, abrí-lo

NotesDatebase O objeto NotesDatabase criado recentemente

GetDbDirectory Dado o nome servidor, cria um novo objeto NotesDbDirectory que pode ser usado para listar os bancos de dados num servidor

NotesDbDirectory

O objeto Notes DbDirectory criado recentemente

GetEnvironmentString

Dado um nome de uma variável de ambiente string, pega seu valor. Quando rodando em um servidor, pega o valor NOTES.INI do servidor. Quando rodando em uma Estação de Trabalho usa o NOTES.INI do usuário atual

Variant O valor da variável do ambiente

GetEnvironmentValue

Como em GetEnvironmentString mas para uma variável de ambiente numérica

Variant O valor da variável de ambiente

SetEnvironmentVar

Dado o nome de uma variável de ambiente e valor novo, armazena o novo valor no arquivo NOTES.INI apropriado. Quando rodando em um servidor usa o NOTES.INI do servidor. Quando rodando em uma estação de trabalho, usa o NOTES.INI do usuário corrente

Nenhum Nenhum

UpdateProcessedDoc

Somente para agentes script, marca um documento como tendo sido processado por um agente

Nenhum Nenhum

5.1 Achando o Banco de Dados Atual

Um dos usos mais comuns da classe NotesSession é pegar o nome do banco de dados atual, isto é, aquele no qual o script está rodando. A propriedade CurrentDatabase retorna um objeto NotesDatabase representando o banco de dados no qual o script está rodando.

O exemplo a seguir mostra o nome de um banco de dados no qual o script está rodando:

Dim s As New NotesSession


Set db = s.CurrentDatabase

MessageBox(“O script está executando no banco de dados” &

db.CurrentDatabase)

Usar CurrentDatabase é uma técnica útil porque significa que você não tem que saber o nome do banco de dados dentro do seu script.

5.2 Achando Aonde o Script está Rodando

Use a propriedade IsOnServer da classe NotesSession quando precisar saber se seu script está rodando em um servidor ou estação de trabalho. Se seu script está rodando em um servidor, IsOnServer retorna verdadeiro(true).

Por exemplo, se um agente deve ser rodado em um servidor, o código seguinte mostra uma mensagem apropriada caso você tente executá-lo em uma estação de trabalho:



If not s.IsOnServer Then

MessageBox(“Este código deve ser usado no servidor”)

End If

5.3 Checando Quem Está Rodando o Script

A classe NotesSession lhe fornece três maneiras diferentes de achar o nome da pessoa ou servidor que está rodando o script.

A propriedade UserName retorna o nome completo do usuário atual. Para scripts rodando em uma estação de trabalho, o usuário atual é a pessoa atualmente logada ao Notes na estação de trabalho. Para scripts executando em um servidor, o usuário atual é sempre o servidor. Use esta propriedade quando for importante que você saiba o nome completo do usuário corrente.

Por exemplo, quando eu executar um agente script manualmente através do menu agente na minha estação de trabalho, UserName retorna meu NOME/EBS. Se eu mudar o script de forma que seja desencadeado na fila a cada uma hora e depois rodar no servidor, UserName retorna SERVIDOR/EBS.

Quando você precisa somente a parte comum do nome de um usuário, use a propriedade CommonUserName. Como seu nome sugere, esta propriedade retorna exatamente a parte comum do nome do usuário atual. Quando eu executo um agente manualmente através do menu agente na minha estação de trabalho, CommonUserName retorna meu NOME; quando eu rodo o mesmo agente em um servidor, ela retorna SERVIDOR.

A terceira propriedade que lhe dá o nome do usuário é a propriedade EffectiveUserName. Para scripts rodando em servidores esta propriedade retorna exatamente o mesmo que a propriedade UserName. A diferença ocorre para scripts rodando em servidores onde EffectiveUserName retorna o nome completo do último usuário a editar o script.

5.4 Checando Como o Notes é definido (Set-Up)

Você pode achar tanto o tipo de sistema de operação como a versão do Notes na qual seu script está executando. A propriedade Plataform permite-lhe achar o tipo de sistema de operacionalb. Da mesma forma que muitas outras propriedades do NotesSession, Plataform lhe dá uma resposta diferente dependendo de onde o script está rodando. Para scripts rodando em uma estação de trabalho, Plataform retorna o tipo de sistema de operacional da estação. Para scripts rodando em um servidor, o tipo de sistema de operacional do servidor é retornado.

NOTA

“Plataform” não retorna detalhes completos do sistema de operação. Por exemplo, retorna UNIX para AIX, Sun, HP-UX and SCO.

Use a propriedade NotesVersion do NotesSession para achar em qual versão do Notes o script está executando.


Dim strVersion As String

StrVersion = s.NotesVersion

Messsagebox(strVersion)

End Sub

Você pode usar a propriedade Internacional para checar as definições internacionais atuais, do tipo símbolo atual e o formato data/hora.

5.5 Lendo e Escrevendo para Variáveis de Ambiente

A classe NotesSession contém três métodos para lhe dar acesso às variáveis de ambiente Notes armazenadas no NOTES.INI ou arquivos preferenciais. Se seu script está executando em um servidor, o NOTES.INI do servidor é usado; caso contrário o NOTES.INI do usuário é usado.

Você pega uma variável de ambiente usando tanto GetEnvironmentString ou GetEnvironmnetValue. Use GetEnvironmentString para retornar uma variável de ambiente string e use GetEnvironmentValue para pegar uma variável de ambiente numérica. Com cada método, você fornece o nome e o tipo da variável de ambiente e o método retorna o valor. Existem dois tipos de variáveis de ambiente: variável de usuário e variáveis de sistema. Nomes de variáveis de usuário começam com o símbolo dollar, nomes de variáveis de sistema não.

Use SetEnvironmentVar para criar uma nova variável de ambiente ou mudar o valor de uma já existente. Você fornece o nome da variável e seu novo valor. O qual deve ser uma string, um inteiro, ou uma data. O método converte o valor fornecido em uma string de texto e escreve-a para o NOTES.INI com o nome que você forneceu.

5.6 Abrindo o Banco de Dados

Use o método GetDatabase com o nome do servidor e do arquivo para abrir um banco de dados existente. Se o banco de dados fornecido existe no servidor específico com nome de arquivo correto, um novo objeto NotesDatabase é criado e aberto. Se, por alguma razão, o banco de dados não for encontrado, o método retorna um objeto NotesDatabase fechado. O método GetDbDirectory é útil quando você precisa processar um conjunto de bancos de dados no diretório de dados. Quando fornecido com o nome de um servidor, o método retorna um objeto NotesDbDirectory, o qual aponta para o diretório de dados do Notes naquele servidor. Você pode então usar métodos nas classes NotesDbDirectory e NotesDatabase para processar os bancos de dados no diretório.

5.7 Trabalhando com Agentes

Uma das características realmente úteis da classe NotesSession é sua capacidade para armazenar informações da hora que um agente executou por último. Desta maneira, você pode construir uma história do que um agente tem feito.

Existem três propriedades que você pode usar a partir do agente LotusScript para pegar informações sobre hora que um agente executou por último.

A propriedade LastRun retorna a data que o agente foi executado por último ou 11/30/1999 se o agente nunca tiver sido executado antes. O seguinte script checa se um agente já foi executado anteriormente:

Sub Initialize


Dim datLastRun As Variant

DatLastRun = s.LastRun

If datLastrun = Cdat(“11/30/1999”) then

Messagebox(“Este agente não foi executado antes”)

ElseMessagebox(“Este script foi executado pela última vez em “& Cstr(datLAstRun))

End If

End Sub

A propriedade LastExitStatus é o código de saída que o Administrador de Agente retornou da última vez que o agente atual executou. Se o agente executou sem erros, o LastExitStatus é 0 (zero).

A propriedade SavedData retorna um objeto NotesDocument que o agente corrente pode usar para armazenar dados. É assim que você salva informações entre execuções. Por exemplo, suponha que um agente é executado toda noite para checar se alguém foi

adicionado ou removido da ACL de um banco de dados. Os nomes das pessoas no ACL podem ser armazenados no documento SaveData, cada vez que o agente executa de forma que ele pode então checar os nomes salvos ao invés dos nomes atuais.

Existe também um método relacionado de agente na NotesSession, o método UpdateProcessedDoc. Ele é usado em conjunto com alguns métodos e propriedades da classe NotesDatabase para assegurar que documentos serão processados somente uma vez por agente. Veremos um exemplo de como usar o método UpdateProcessedDoc mais tarde na sessão NotesDatabase.

5.8 Trabalhando com Outros Objetos Notes

Você pode criar vários outros objetos Notes usando métodos na classe NotesSession. Use CreateDateRange, CreateDateTime, CreateLog e CreateNewsletter para criar objetos NotesDateRange, NotesDateTime, NotesLog e NotesNewsletter. Veremos estes objetos em maiores detalhes posteriormente nas sessões NotesDateRange, NotesDateTime, NotesLog e NotesNewsletter.

6 NotesDbDirectory

Esta é uma das classes mais fáceis para entender. Possui somente uma propriedade e três métodos. Representa o diretório de dados do Notes em um servidor ou estação de trabalho específicos e seu uso principal é percorrer um conjunto de bancos de dados de um tipo específico ou que obedeçam certos critérios. Por exemplo, você pode percorrer todos os bancos de dados, em um servidor, que estão disponíveis para replicação.

Você cria um novo objeto NotesDbDirectory de duas formas: Você pode usar o método GetDbDirectory da NotesSession como vimos na última seção, ou você pode usar o método New. Você especifica o tipo de banco de dados que você está procurando; veja a tabela 3.10 para detalhes.

Tabela 3.10 Tipos básicos para NotesDbDirectory

Para Achar Este Tipo de Banco de Dados Use Esta Constante...Qualquer banco de dados Notes DATABASEQualquer banco de dados modelo TEMPLATETodos os bancos de dados Notes disponíveis para replicação

REPLICA_CANDIDATE

Todos os bancos de dados Notes que podem ser um modelo TEMPLATE_CANDIDATE

Após você ter um objeto NotesDbDirectory, você pode acessar o banco de dados no diretório, usando GetFirstDatabase e GetNextDatabase. Você pode usar a propriedade Name para encontrar o nome do servidor no qual você está acessando o diretório:




Dim DbDir As NotesDbDirectory


Dim strDbsAvailToReplicate


Set DbDir = New NotesDbDirectory(“Rubi”)

Ser db = dbDir.GetFirstDatabase(REPLICA_CANDIDATA)

Do While Not (db Is Nothing)

StrDbsAvailToReplicate = strDbsAvailToReplicate + db.Ttile + chr(10)

Set db = DbDir.GetNextDatabase

Loop

Call uiDoc.FieldSetText(“ServerName”, DbDir.Name)

Call uiDoc.FieldSetText(“DbsAvailToReplicate”, strDbsAvailToReplicate)

End Sub

O script acima usa New para criar um novo objeto NotesDbDirectory para servidor “Rubi”. Ele abre então cada banco de dados no servidor que está disponível para replicação e armazena seu nome no campo DbsAvailToReplicate no documento atual. Ele também usa a propriedade Name para armazenar o nome do servidor no campo ServerName. As tabelas 3.11 e 3.12 mostram as propriedades e métodos da classe NotesDbDirectory.

Tabela 3.11 Propriedades da classe NotesDbDirectory

Propriedade Descrição Tipo de Dados UsoName O nome do servidor no qual este

diretório está localizadoString Somente Leitura

Tabela 3.12 Métodos da classe NotesDbDirectory

Propriedade Descrição Tipo de Dados de retorno

Valor de retorno

GetFirstDatabase

Dado um tipo de banco de dados para procurar, retorna o primeiro banco de dados daquele tipo. Você pode procurar qualquer tipo de banco de dados, qualquer modelo, e banco de dados que pode ser replicado, ou qualquer banco de dados que pode ser um modelo.

NotesDatabase O primeiro banco de dados do tipo que você especificou

GetNextDatabase

Se você já tiver usado o método FirstDatabase, retorna o próximo banco de dados do tipo que você especificou

NotesDatabase O próximo banco de dados do tipo que você especificou

New Cria um novo objeto NotesDbDirectory. NotesDbDirectory O objeto criado recentemente

7 NotesDatabase

A classe NotesDatabase representa um banco de dados Notes. Você usa a classe para fazer o seguinte:

• Criar, modificar e excluir bancos de dados;• Criar cópias e replicas de bancos de dados;• Modificar listas de controble de acesso;• Criar documentos;• Encontrar documentos.

A classe também lhe fornece acesso à outras classes, do tipo NotesView, NotesDocumentCollection e NotesDocument. Veja a tabela 3.13 para uma lista de propriedades da classe NotesDatabase. Seus métodos estão listados na tabela 3.14.

Tabela 3.13 Propriedades da classe NotesDatabase

Propriedade Descrição Tipo de Dados UsoACL A ACL para o banco de dados NotesACL Leitura

Agents Todos os agentes definidos no banco de dados

Array of NotesAgents

Leitura

AllDocuments Uma coleção contendo todos os documentos de um banco de dados.


Leitura

Categories Todas as categorias às quais um banco de dados pertence

String Leitura

Created A data que o banco de dados foi criado Variant of type DATE

Leitura

CurrentAccessLevel

O nível de acesso ACL para o usuário atual

Integer Constante

Leitura

DelayUpdates Verdadeiro(true) se múltiplas atualizações em documentos em um servidor são processadas juntas para melhor performance

Boolean Leitura Gravação

DesignTemplateName

O nome do modelo de criação para o banco de dados.

String Leitura

FileName O nome e extensão do arquivo do banco de dados.

String Leitura

FilePath O caminho completo e nome do arquivo do banco de dados incluindo “drive” de leitura, diretório, nome de arquivo e extensão.

String Leitura

Forms Os formulários no banco de dados. Array of NotesForm objects.

Leitura

IsFTIndexed Verdadeiro(true) se o banco de dados tem índice de texto completo.

Boolean Leitura

IsMultiDBSearch Verdadeiro(true) se o banco de dados tem índice de texto completo.

Boolean Leitura

IsOpen Verdadeiro(true) se o banco de dados estiver aberto.

Boolean Leitura

IsPrivateAddress Verdadeiro(true) se o banco de dados é Boolean Leitura

Book um Livro de Endereço Pessoal.IsPublicAddressBook

Verdadeiro(true) se o banco de dados é um Livro de Endereço Público.

Boolean Leitura

LastFTIndexed Para bancos de dados com um índice completo de texto, a data que o índice foi atualizado da última vez. 30/12/1999 para bancos de dados sem índice completo de texto.

Variant of type DATE

Leitura

LastModified A data que o banco de dados foi modificado pela última vez.


Leitura

Managers Todas as pessoas, grupos e servidores que são os administradores do banco de dados.


Leitura

Parent O NotesSession que contém o banco de dados.

NotesSession Leitura

PercentUsed A percentagem do banco de dados que está em uso atualmente.

Double Leitura

ReplicaID O ID de replica(16-caractere) para o banco de dados.

String Leitura

Server O nome do servidor no qual o banco de dados está armazenado.

String Leitura

Size O tamanho, em bytes, do banco de dados. Double LeituraSizeQuota O tamanho máximo, em bytes, até o qual o

banco de dados pode crescer.Long Leitura/Gravação

TemplateName Para bancos de dados que são modelos, o nome do modelo. Se o banco de dados não for modelo, retorna uma string vazia.

String Leitura

Title O título do banco de dados. String Leitura/GravaçãoUnprocessedDocuments

Todos os documentos que são considerados para ser “unprocessed” pelo script .


Somente Leitura

Views Todas as visões e pastas públicas dentro do banco de dados. Se o banco de dados estiver armazenado localmente, pastas pessoais são incluídos.

Variant of Notes Views

Leitura

Tabela 3.14 Métodos da classe NotesDatabase

Propriedade Descrição Tipo de Dados Retornados

Valor Retornado

Close Fecha o banco de dados. Nenhum NenhumCompact Compacta um banco de dados local.

Perceba que você não pode usar este método para compactar o banco de dados aonde o script está rodando.

Long O número de bytes recuperados na compactação do banco

Create Dado um servidor e um nome de arquivo, cria um novo banco de dados.

Nenhum Nenhum

CreateCopy Dado um servidor e um nome de arquivo, cria uma cópia do banco de dados. Dá à cópia o mesmo título e ACL do original.

NotesDatabase Um objeto NotesDatabase representando a cópia criada recentemente

Create Document

Cria um documento novo e vazio no banco de dados. Note que você deve

NotesDocument O documento criado recentemente

salvar o documento antes de de fechar o banco; caso contrário, o documento será perdido.

CreateFormTemplate

Dado um servidor, nome de arquivo e o nome de um modelo, cria um novo banco de dados baseado no modelo.

NotesDatabase Um objeto do banco de dados Notes representando o banco criado recentemente

CreateReplica Dado um servidor, nome de arquivo, cria uma cópia réplica do banco de dados. Fornece a réplica com o mesmo título e ACL do original.

NotesDatabase Um objeto do banco de dados Notes represen-tando o banco criado recente-mente

FTSearch Dada uma string representando uma válida consulta de texto completo, o texto completo procura o banco de dados.


Uma coleção de documentos atendendo aos critérios da consulta, classificada de forma que os documentos mais relevantes estão em primeiro lugar

GetAgent Fornece um agente dado seu nome. NotesAgent O agenteGetDocument ByID

Dado o NotesID de um documento, encontra o documento.

NotesDocument O documento

GetDocument ByUNID

Similar ao anterior porém usa o UNID. NotesDocument O documento

GetDocument ByURL

Sendo banco de dados Notes é um Web Navigator, retorna o documento Notes que corresponde à página WEB com URL que você especificar. Se necessário você pode forçar o banco de dados Navigator Web para recarregar a página Web.

NotesDocument O documento correspondente à URL

GetForm Pega um formulário dado o seu nome ou alias.

NotesForm O formulário

GetProfileDocument

Pega um documento Profile do banco de dados.

NotesDocument O documento profile

GetURL Header

Para o banco de dados Web Navigator, dado um URL e string de cabeçalho, retorna a informação do cabeçalho URL requerida.

String A informação de cabeçalho

GetView Dado o nome ou alias de uma visão ou pasta, retorna a visão ou pasta.

NotesView A visão ou pasta requisitado

GrantAccess Muda o ACL para o banco de dados para dar à pessoa, grupo ou servidor um nível de acesso específico.

Nenhum Nenhum

New Cria um novo objeto banco de dados Notes. Note que este método não cria um novo banco de dados no disco.

Banco de dados Notes

O objeto criado recentemente

Open Dado um servidor e um nome de arquivo, abre um banco de dados existente.

Boolean Verdadeiro se o banco de dados foi encontrado e aberto com sucesso

OpenBy ReplicaID

Similar ao Open, mas usa o nome do servidor fornecido e replica ID para

Open Verdadeiro se o banco de dados foi

encontrar o banco de dados encontrado e aberto com sucesso

OpenIf Modified

Dado um servidor, nome de arquivo e data abre um banco de dados existente, sob a condição que tenha sido modificado desde a data que você especificou.

Boolean Verdadeiro se o banco de dados tiver sido encontrado e aberto com su-cesso

OpenMail Abre o correio do banco de dados do usuário atual.

Nenhum Nenhum

OpenURLDB Abre o Navegador Web default do banco de dados.

Boolean Verdadeiro se o banco de dados tiver sido encontrado e aberto com sucesso

OpenWithFailOver

Dado um servidor e nome de arquivo, tenta abrir o banco de dados. Se o mesmo não pode ser aberto e o servidor está em um grupo de servidores, tenta abrir uma réplica do banco de dados em outro servidor em grupo.

Boolean Verdadeiro se o banco de dados foi encontrado e aberto com sucesso

QueryAccess Dado o nome de uma pessoa, grupo ou servidor, devolve seus níveis de acesso ao banco de dados.

Integer Constant O nível de acesso

Remove Exclui o banco de dados. Nenhum NenhumReplicate Dado o nome de um servidor, replica o

banco de dados com sua réplica naquele servidor.

Boolean Verdadeiro se o banco de dados foi replicado com sucesso

RevokeAccess Remove uma pessoa, grupo ou servidor do ACL para o banco de dados.

Nenhum Nenhum

Search Dada uma fórmula de seleção do Notes e uma data isolada, procura no banco de dados todos os documentos que combinam com a fórmula.

NotesDocument Collection

Todos os documentos que com binam com a fórmula e têm sido modificados desde a data separada

Unprocessed FTSearch

Somente para agentes script, o mesmo que FTSearch, exceto que só são procurados aqueles documentos que o agente considera não processados.


Os documentos

Unprocessed Search

Somente para agentes script, o mesmo que Search, exceto que só são procurados aqueles documentos que o agente considera não processados.


Os documentos

UpdateFT Index

Para qualquer banco de dados com um índice de texto completo, atualiza o índice. Para banco de dados local, cria o índice, se necessário.

Nenhum Nenhum

7.1 Criando um Banco de Dados

A classe NotesDatabase lhe oferece vários métodos para criar um novo banco de dados em um disco. O mais simples é o Create, o qual cria um novo banco de dados, em branco. Você especifica o servidor e o nome de arquivo para usar e se é para abrir o banco após ter sido criado.

NOTA

Um banco de dados tem que ser aberto antes que você possa usar a maioria de suas propriedades ou métodos.

Após você ter criado um novo banco de dados ou ter aberto um existente, você pode usar quaisquer dos métodos seguintes para criar novos bancos baseados no original: CreateCopy, CreateReplica ou CreateFromTemplate.

Use CreateCopy para criar uma cópia do banco de dados atual. A cópia contém todos os formulários, visões e agentes do original, tem o mesmo ACL e o mesmo título. Você pode criar uma réplica do banco de dados atual usando o método CreateReplica. Você fornece um nome de servidor e um nome de arquivo e o método cria uma réplica do banco de dados na sua nova localização. Se o banco de dados atual é um modelo, você pode criar um novo banco de dados baseado no modelo usando CreateFromTemplate. Como com os outros métodos, você fornece um servidor e nome de arquivo para o novo banco. Você pode também especificar que o novo banco de dados deverá herdar futuras mudanças de estruturas do modelo. O exemplo a seguir usa esses métodos para criar novos bancos de dados.



Dim dbTemplate As New NotesDatabase(“Sapphire”, “report.ntf”)

Dim dbReplica As NotesDatabase


‘ Cria uma réplica do banco de dados corrente em um servidor diferente

Set dbReplica = db.CreateReplica(“Diamante”,”stock.nsf”)

‘ Cria uma copia do banco de dados corrente

Set dbCopy = db.CreateCopy(“Diamante”,”backup\stock.nsf”)

DbNew.Title = “ Backup of New Stock Control Levels “

‘ Cria um novo banco de dados baseado em um modelo

Set dbNew = dbTemplate.CreateFromTemplate( “Diamante”, “report.nsf”,True)

DICA

Scripts rodando em um servidor podem somente criar ou acessar bancos de dados em um servidor.

7.2 Abrindo, Fechando e Excluindo um Banco de Dados.

Antes que você acesse quaisquer das propriedades ou métodos de um banco de dados, o mesmo deve ser aberto. Após abrí-lo, todas as suas propriedades e métodos estarão disponíveis à você.

Você pode usar a propriedade IsOpen para checar se o banco de dados está aberto. Se não estiver, a maneira mais simples para abrí-lo é usar o método Open. Você fornece um servidor e um nome de arquivo e o banco de dados é aberto – se existir – e o script tem pelo menos acesso de leitura ao mesmo. Se você conhece o ID da réplica do banco de dados, você pode usar o método OpenByReplicaID. Ele trabalha da mesma maneira que o método Open, mas você fornece o ID da réplica ao invés do servidor e do nome do arquivo. OpenIfModified é útil para agentes que devem checar periodicamente atualizações para bancos de dados. Você fornece um servidor e um nome de arquivo como para o Open, mas, em adição, você também fornece o objeto NotesDateTime. O banco de dados somente é aberto se tiver sido modificado desde a data representada pelo objeto NotesDateTime. Se seus servidores Notes estão configurados como parte de um grupo de servidores, você pode usar o novo método OpenWithFailover para tentar abrir um banco de dados em um servidor e se mal sucedido automaticamente tente abrir a réplica do banco de dados em outro servidor no grupo.

Existe também uma dupla de métodos especializados. OpenMail encontra e abre o banco de dados de correio para o usuário atual. Como em alguns outros métodos, OpenMail comporta-se diferentemente executando em uma estação de trabalho e executando em um servidor. Em uma estação de trabalho, ele encontra o banco de dados de correio para o usuário corrente. Em um servidor, ele encontra o banco de dados de correio para a última pessoa que modificou o script.

Se um Navegador Web Notes tiver sido definido em seu local, você pode usar o OpenURLDb para achá-lo e abrí-lo.

Todos os métodos de abertura retornam verdadeiro(true) se o banco de dados tiver sido aberto com sucesso e falso(false) se o mesmo não tiver sido aberto por qualquer razão.

DICA

Para abrir um banco de dados, seu script deve ter pelo menos acesso de leitura. Desta forma, se o script estiver executando na sua estação de trabalho, você deve ter acesso de leitura ao banco que deseja abrir. Se o script estiver rodando em um servidor, o servidor deve ter acesso de leitura ao banco de dados.

Quando seu script termina de executar, o Notes automaticamente fecha todos os bancos de dados que o script abriu. Se você necessita explicitamente fechar o banco de dados, use o método Close. Após ter fechado um banco, você não pode acessar seus métodos e propriedades. Use o método Remove se você desejar excluir o banco de dados.

7.3 Trabalhando com um Banco de Dados

Após ter aberto um banco de dados, uma grande quantidade de informações sobre ele estará disponível à você. Existem propriedades que de dizem quando foi criado (Created) ou modificado por último (LastModified). Você pode pegar o servidor do banco de dados , nome do arquivo e ID da réplica usando as propriedades server, FilePath e ReplicaID. Você pode achar seu título usando a propriedade Title e checar em que

categorias o banco de dados está usando a propriedade Categories. A propriedade Parent de um banco de dados retorna o NotesSession que contém o banco de dados.

Se você está trabalhando com índices de texto completo, você pode checar se o banco de dados está indexado usando a propriedade IsFTIndexed ou usar LastFTIndexed para encontrar data e hora que o índice foi atualizado pela última vez. Você pode usar o novo método IsMultiDbSearch para checar se o banco contém um índice de texto completo para múltiplos banco de dados. Se você necessitar atualizar o índice você pode chamar o método UpdateFTIndex. Você pode também usá-lo para criar um índice de texto completo para um banco de dados, desde que o banco esteja armazenado localmente em uma estação de trabalho. Se você tentar usá-lo em um banco de dados “server-based” que não possui índice de texto completo, você recebe um erro. O exemplo seguinte checa se um banco de dados possui um índice de texto completo e cria um, se necessário. Se o banco de dados já possui um índice de texto completo, o script atualiza-o somente se o banco de dados tiver sido modificado desde a última vez que o índice completo foi atualizado.




If (Not db.IsFTIndexed) then

Print “Criando um texto de índice completo... ”

Call db.UpdateFTIndex(True)

End If

If (db.LastModified > db.LastFTIndexed) Then

Print “Atualizando um texto de índice completo...”

Call db.UpdateFTIndex(False)

End If

Print “ Finalizado.”

End Sub.

Você pode encontrar o tamanho do banco de dados usando as propriedades Size, SizeQuotae PercentUsed. Size lhe dá o tamanho do banco de dados em bytes e PercentUsed lhe dá o percentual deste tamanho que contém dados (versus espaços vazios). SizeQuota retorna o máximo de bytes que seu administrador Notes tem permitiu para este banco de dados. Por exemplo, você pode usar Size e SizeQuota para monitorar o banco de dados e emitir um aviso se seu tamanho aproximar-se do limite da quota. Ou, se o PercentUsed for mais alto que um certo percentual, você pode usar o método Compact para reaproveitar o espaço vazio.

DICA

Você só pode compactar bancos de dados locais usando o método Compact. Então se você executar um script na sua estação de trabalho, você só pode compactar um banco de dados em sua estação de trabalho. Se você precisar compactar bancos de dados do servidor, assegure-se de executar o script no servidor.

Se o banco de dados é um modelo, você pode achar o nome do modelo usando a propriedade TemplateName. Da mesma forma, se o bando de dados herdar sua estrutura de um modelo, você pode achar o nome do modelo do qual ele herdou a estrutura usando a propriedade DesignTemplateName.

Se você estiver interessado no Livro de Endereços Notes e tiver usado a propriedade AddressBooks da NotesSession para pegar o Livro de Endereços disponível atualmente, você pode checar cada um, se é um livro de endereço público ou privado. IsPublicAddressBook e IsPrivateAddressBook retorna verdadeiro(true) se o banco de dados é do tipo apropriado. Por exemplo, o script seguinte conta o número de livros de endereços públicos e privados disponíveis atualmente:



Dim AddressBooks As Variant

Dim iPublicAddressBooks As Integer

Dim iPrivateAddressBooks As Integer

AddressBooks = s.AdressBooks

Forall Book in AddressBooks

If Book.IsPublicAddressBook Then

iPublicAddressBooks = iPublicAddressBooks + 1

End If

If Book.IsPrivateAddressBook Then

iPrivateAddressBooks = iPublicAddressBooks + 1

End If

End Forall

MessageBox “Este sessão tem “ & Str$(iPublicAddressBooks) & “ livros endereços

Públicos e “ & Str$(iPrivateAddressBooks) & “livros endereços privados

End Sub

Você pode pegar uma lista de todos os agentes em um banco de dados usando as propriedade Agents. Atualmente, o que você pega é uma array de objetos NotesAgent. Você pode então usar as propriedades da classe NotesAgent para mostrar informações

sobre cada agente. Se você conhece o nome de um agente, você pode pegar seu objeto NotesAgent correspondente usando o método GetAgent. Da mesma forma, você pode usar a propriedade Forms e o método GetForm para trabalhar com formulários no banco de dados.

Você pode forçar o banco de dados a replicar com um servidor específico usando o método Replicate. Você fornece o nome do servidor e o método inicia a replicação e retorna verdadeiro(true) se a replicação foi bem sucedida.

7.4 Trabalhando com a Lista de Controle de Acesso(ACL)

A classe NotesDatabase fornece-lhe vários métodos e propriedades para permitir-lhe examinar e modificar definições de ACL para o banco de dados. Você pega o ACL para o banco de dados usando a propriedade ACL. Esta retorna um objeto NotesACL representando o ACL atual. Você pode então usar os métodos e propriedades das classes NotesACL e NotesACLEntry para ler e modificar o ACL.

Mesmo que você não use um objeto NotesACL, você pode ainda trabalhar com o ACL para o banco de dados. Você pode usar o método QueryAccess para checar o nível de acesso para uma pessoa, grupo ou servidor. Forneça ao método o nome de uma pessoa, grupo ou servidor e ele retornará uma constante integer representando o nível de acesso atual ao banco de dados para o nome que você especificou. Veja a tabela 3.15 para detalhes.

Tabela 3.15 Constantes Níveis de Acesso para NotesACL

Nível de Acesso Constante

Nenhum ACCLEVEL NOACCESS

Depositor ACCLEVEL DEPOSITOR

Leitor ACCLEVEL LEITOR

Autor ACCLEVEL AUTOR

Editor ACCLEVEL EDITOR

Designer ACCLEVEL DESIGNER

Administrador ACCLEVEL ADMINISTRADOR

Você pode usar QueryAccess para checar se um usuário tem permissão para executar certas tarefas no banco de dados. Por exemplo, o script seguinte checa se o usuário atual tem pelo menos acesso de Edição ao banco de dados:




Dim iAccessLevel AS Integer


iAccessLevel = db.QueryAccess(s.UserName)

Select Case iAccessLevel

Case ACLLEVEL_MANEGER

Print “ Você tem acesso de designer para este banco de dados”

Case ACLLEVEL_EDITOR

Print “ Você tem acesso editor para este banco de dados”

Case ElsePrint “ Você não tem acesso editor para este banco de dados”

End Select

End Sub

Você pode achar o nível de acesso do usuário atual usando a propriedade Notes DatabaseCurrentAccessLevel. Esta retorna o mesmo conjunto de constantes integer como QueryAccess. Você pode também pegar uma lista de nomes de pessoas, grupos ou servidores que tenham acesso de Administração ao banco de dados usando a propriedade Managers. Esta propriedade retorna uma lista de nomes de administradores do banco de dados.

Se você necessitar alterar o nível de acesso de alguém, você tem duas maneiras: usar a propriedade ACL para pegar o objeto NotesACL e então usar seus métodos ou usar os métodos GrantAccess e RevokeAccess do NotesDatabase. Use o GrantAccess para dar a uma pessoa, grupo ou servidor um nível de acesso específico. Use RevokeAccess para remover um nome do ACL.

7.5 Criando um Documento

Use CreateDocument para criar um novo documento no banco de dados. Este método retorna um objeto NotesDocument, o qual você pode então usar para adicionar dados e salvar o novo documento. Veremos NotesDocument em detalhes na seção NotesDocument.

7.6 Encontrando um Documento

Todos os documentos no banco de dados Notes têm dois únicos números que podem ser usados para identificá-los. O “Note ID” é um ID de 8 (oito) caracteres que unicamente identifica um documento dentro de um banco de dados particular. O “Notes ID” é específico para o banco de dados, isto é, uma cópia do documento em uma réplica do banco de dados pode ter um Note ID diferente. O ID universal para um documento é um ID de 32 caracteres que unicamente identifica o documento em todas as cópias do banco de dados. A classe NotesDatabase tem métodos que permitem-lhe encontrar um documento tanto pelo seu “Notes ID” como pelo seu “Universal ID”.

Se o banco de dados atual é um banco de dados Navegador Web, você pode encontrar um documento através de seu "Uniform Resource Locator" (URL) usando GetDocumentByURL. Por exemplo, para acessar a última atualização da home page do Lotus do banco de dados Navegador Web, você pode usar o seguinte:


Dim dbWebNavigator As NotesDatabase

Dim LotusHomePage As NotesDocument

‘Assume que o banco de dados corrente é o navegador da Web

Set dbWebNavigator = s.CurrentDatabase

Set LotusHomePage = dbWebNavigator.GetDocumentByURL(“ http://www.lotus.com”, True)

Se você precisar fazer coisas ornamentadas com o Hypertext Transport Protocol (HTTP) informação de cabeçalho para página Web, você pode usar GetURLHeaderInfo para acessar um valor de cabeçalho específico. Forneça o URL e o nome do valor de cabeçalho que você deseja e o método retorna o valor do cabeçalho. Se a página Web não contém o cabeçalho requisitado, o método retorna uma string nula.

7.7 Achando um grupo de documentos

Você pode achar todos os documentos de um banco de dados usando a propriedade AllDocuments. AllDocuments retorna um NotesDocumentCollection contento todos os documentos do banco de dados. Se você quer achar um subconjunto de documentos do banco de dados, existem dois métodos diferentes que você pode usar; Search e FTSearch.

Se você quer selecionar os documentos usando uma fórmula de seleção Notes, você pode usar o método Search. Você fornece Search com os seguintes parâmetros:

• Uma fórmula de seleção Notes, tal como Form = “Main Topic”;

• Um objeto NotesDateTime. Somente documentos que foram modificados desde a data especificada por um objeto date-time são incluídos nos resultados de busca;

• O número de documentos retornados (ou 0 ou todos os documentos).

O método retorna um NotesDocumentCollection contento todos os documentos que satisfazem a seleção e o critério de data.

Se os documentos que você está procurandos são melhor encontrados por uma consulta de texto completo, use o método FTSearch. Com FTSearch, você fornece dois parâmetros, uma consulta de texto completo e o número de documentos a retornar. O método busca o banco de dados e retorna um NotesDocumentCollection contento os documentos correspondentes ordenados na ordem de relevância.

Quando você está trabalhando com agentes e você quer restringir o cojunto de documentos retornados para somente incluir aqueles agentes que não foram processados, você pode usar a propriedade UnprocessedDocuments e os métodos UnprocessedSearch e UnprocessedFTSearch. Cada documento e agente definidos como não processados dependem de como cada agente é definido.Veja a ajuda do Notes para detalhes de como um agente define um documento não processado.

http://www.lotus.com/

Você pode usar o método GetView para achar uma visão específica no banco de dados. Depois de você ter a visão, você pode usar os métodos de procura da classe NotesView para achar documentos com a visão que lidera(encabeça, chefia) agradavelmente para a próxima classe.

8 NotesView

A classe NotesView deixa-o trabalhar com visões e pastas do Notes e os documentos que elas contém.

Usando as propriedades e métodos NotesView você pode fazer o seguinte:

• Examinar atributos de visão;• Navegar para cima e para baixo de uma visão hierárquica;• Procurar por documentos na visão;• Excluir uma visão.

Veja a tabela 3.16 para ver todas as propriedades da classe NotesView. Seus métodos são listados na tabela 3.17. Note que você não pode criar novas visões em um banco de dados Notes a partir de LotusScript, você pode somente acessar visões existentes. Você pode obter uma visão específica usando os método GetView da classe NotesDatabase, ou você pode obter todos as visões no banco de dados através da sua proprieadade Views.

Tabela 3.16 Propriedades da classe NotesView

Propriedade Descrição Tipo de Dado UsoAliases O aliases de uma visão. Array of string LeituraAutoUpdate Deixe-a como true se a visão front-end é

atualizada automaticamente quando da atualização da visão back-end.

Boolean LeituraGravação

Columns Todas as colunas na visão ou pasta. Array of Notes ViewColumns

Leitura

Created A data e hora em que a visão ou pasta foi criada.

Variant of date type

Leitura

IsCalendar Verdadeiro se a visão é um visão de calendário.

Boolean Leitura

IsDefaultView Verdadeiro se a visão é a padrão Boolean LeituraIsFolder Verdadeiro se o objeto é uma pasta Boolean LeituraLastModified A data e hora quando a visão ou pasta foi

modificada pela última vez.Variant of type date

Leitura

Name Pode ser seu nome, alias ou ambos. String LeituraParent O banco que contém a visão ou pasta. NotesDatabase LeituraProtectReaders Defina como verdadeiro para proteger o

item $Readers durante a replicação.Boolean Leitura

GravaçãoReaders O nome das pessoas, grupos e

servidores que podem ler a visão,Array of string Leitura

GravaçãoUniversalID Um ID de 32 caracteres que identifica a

visão ou pasta em todas as réplicas de um banco de dados particular.

String Leitura

Tabela 3.17 Métodos da classe NotesView


Valor Retornado

Clear Se a visão foi filtrada usando uma busca de texto completo, limpa a visão e todos os documentos são mostrados.

Nenhum Nenhum

FTSearch Dado uma string representado uma consulta de texto completo, encontra o banco de dados e mostra as visões que satisfazem a consulta.

Integer O número de documentos que satisfazem a consulta

GetAllDocuments ByKeys

Dado uma chave, acha todos os documetnos na visão que satisfazem a chave.


Uma coleção de documentos que satisfazem a consulta

GetChild Dado um documento na visão, acha a primeira reposta do documento.

NotesDocument A primeira resposta do documento

GetDocumentBy Key Dado uma chave, acha o primeiro documento que possui a chave fornecida.

NotesDocument O primeiro documento com a chave

GetFirstDocument Obtém o primeiro documento da visão.

NotesDocument O primeiro documento da visão

GetLastDocument Obtém o último documento da visão. NotesDocument O último documento da visão

GetNextDocument Obtém o próximo documento da visão a partir do documento atual.

NotesDocument O próximo documento

GetNextSibling Dado um documento de uma visão, acha o próximo documento que tem o mesmo nível do documento atual.


GetNthDocument Dado um índice de uma visão, acha o documento na posição do documento.


GetParentDocument Dado qualquer documento resposta, acha o documento pai.

NotesDocument O documento pai

GetPrevDocument Dado Qualquer documento na visão, acha o documento anterior.


GetPrevSibling Dado um documento em uma visão, acha o documento anterior com o mesmo nível do documento fornecido.


Refresh Atualiza a visão para mostrar as possíveis mudanças.

Nenhum Nenhum

Remove Exclui a visão de um banco de dados.

Nenhum Nenhum

8.1 Trabalhando com propriedades de visão

Você pode achar o nome de uma visão usando a propriedade Name. Se você precisa achar a aliases para uma visão, você pode obtê-las usando a proprieadade Aliases.

Você pode checar se está trabalhado com uma visão ou pasta lendo a propriedade IsFolder.

Use Created e LastModified para verificar quando uma visão foi criada e a última vez que foi modificada. Você pode checar se uma visão é a padrão em um banco de dados usando a propriedade IsDefaultView.

A propriedade Columns lhe dá acesso a todas as colunas de uma visão ou pasta. Quando você lê a propriedade, você obtém uma array contento um objeto NotesViewColumn para cada coluna na visão. Você pode usar Columns em um loop para obter todas as colunas ou especificar um índice na array para obter uma coluna específica.

8.2 Navegando em uma visão hierárquica

Depois de você ter uma visão, você pode navegar pelos documentos na visão usando uma quantidade variada de métodos. Use GetFirstDocument e GetNextDocument ou GetLastDocument e GetPrevDocument para percorrer todos os documentos na visão na ordem que eles são exibidos. Se você quer ir para um documento baseado na sua posição na visão, use GetNthDocument.

Se você está trabalhando com documentos respostas, você pode usar o métodos para obter documentos em um nível de hierarquia diferente. Depois de achar um documento, você pode usar GetChild para obter o primeiro resposta de um documento ou GetParentDocument para obter seu pai. Para obter documentos no mesmo nível, use GetNextSibling ou GetPrevSIbling.

8.3 Achando um documento na visão

Use GetDocumentByKey para achar um documento baseado nos valores da coluna quer são mostrados na visão. Você fornece uma chave ao formulário de uma array of string para cada valor de coluna que você quer comparar. A primeira string da array é comparada com o conteúdo da primeira coluna categorizada ou ordenada e assim por diante. Se todas as strings correspondem aos valores das colunas, o documento com estes valores de colunas é retornado.

Se sua chave consiste de uma ou mais strings, cada coluna que você compara deve ser ordenada ou categorizada.

8.4 Buscando documentos na visão

Você pode usar a potencialidade das consultas de texto completo do Notes para achar um conjunto de documentos na visão. O método FTSearch deixa-o executar uma consulta de texto completo na visão. A visão é filtrada para incluir somente estes documentos que satisfazem a consulta. Você pode então usar quaisquer métodos de navegação da classe NotesView para processar documentos na visão. Para reinicializar uma visão onde todos os documentos estão incluídos, use o método Clear.

8.5 Atualizando uma visião

Mundanças em uma visão não refletem automaticamente em um objeto NotesView. Para obter as atualizações, use o método Refresh.

8.6 Excluindo uma visão

Você pode usar o método Remove para excluir uma visão permanentemente de um banco de dados

9 NOTESVIEWCOLUMN

O objeto NotesViewColumn representa uma coluna em uma visão ou pasta. Suas propriedades são listadas na tabela 3.18.

Você não pode atualizar diretamente qualquer coluna mas pode consultar suas propriedades. Você pode checar a posição de uma coluna na visão usando a propriedade Position.

NOTA

Todas as posições das colunas iniciam por 1 enquanto os índices das array no LotusScript iniciam com 0. Lembre-se de adicionar 1 ao índice da array para obter a posição da coluna.

A propriedade Title retorna o título da coluna e você pode checar se a coluna está visível usando a propriedade IsHidden. Você pode checar se a coluna está ordenada ou categorizada usando IsSorted e IsCategory.

Os valores de uma coluna são exibidos usando as propriedades Formula ou ItemName. Somente uma dessas propriedades é válida para uma coluna. Se a coluna usa uma fórmula Notes para calcular seu valor, Formula retorna a fórmula como uma string. Se a coluna exibe o conteúdo de um campo, ItemName retorna o nome do campo.

NOTA

NotesViewColumn representa a visualização de uma coluna. Para obter o conteúdo de uma coluna use a propriedade ColumnValues da classe NotesDocument.

Tabela 3.18 Propriedades NotesViewColumn

Propriedade Descrição Tipo de Dado Usado

Formula Representação textual de uma fórmula. String LeituraIsCategory Verdadeiro se a coluna está categorizada. Boolean LeituraIsHidden Verdadeiro se a coluna está oculta. Boolean LeituraIsResponse Verdadeiro se a coluna é somente

resposta.Boolean Leitura

IsSorted Verdadeiro se a coluna está ordenada. Boolean LeituraItemName Se a coluna exibe o valor de um campo, o

nome do campo.String Leitura

Position A posição da coluna na visão. Integer LeituraTitle O título da coluna se ela tiver. String Leitura

10 NOTESDOCUMENT

Notes é tudo sobre trabalho com documentos e a classe NotesDocument é tudo sobre trabalho com documentos usando LotusScript. A classe é rica em funções e grande em termo de número de propriedades e métodos. Mas, depois de você obter um bom conhecimento de como a classe trabalha, você está no caminho de entender como trabalhar com documentos Notes. A tabela 3.19 lista as propriedades da classe NotesDocument e a tabela 3.20 seus métodos.

Tabela 3.19 Propriedades da classe NotesDocument


Authors O nome das pessoas que tem salvo os documentos.

Array of strings Leitura

ColumnValues O valor de uma coluna para um documento

Array of variants Leitura

Created A data de criação do documento. Variant do type data LeituraEmbedded Objects

Todos os objetos ActiveX e OLE no documento.

Array of NotesEmbedded Objects

Leitura

EncryptionKeys A chave usada para encriptar documentos.

String or Array of Strings

Leitura Gravação

EncryptOnSend Verdadeiro(true) se o documento é para ser encriptado quando enviado.


FTSearchScore A contagem de documentos encontrados a partir de uma pesquisa.

Integer Leitura

HasEmbedded Verdadeiro(true) se o documento contem pelo menos um objeto lincado ou arquivo anexado.

Boolean Leitura

IsNewNote Verdadeiro(true) se o documento nunca foi salvo.

Boolean Leitura

IsProfile Verdadeiro(true) se o documento é do tipo profile(perfil).

Boolean Leitura

IsResponse Verdadeiro(true) se o documento é do tipo resposta.

Boolean Leitura

IsSigned Verdadeiro(true) se o documento tem pelo menos uma assinatura.

Boolean Leitura

IsUIdocOpen Verdadeiro(true) se o documento foi acessado por um NotesUIDocument.

Boolean Leitura

IsUnread Verdadeiro(true) se o documento é marcado como não leitura para o usuário corrente.

Boolean Leitura

Items Todos os itens armazenados em um documento.

Array of NotesItems Leitura

Key A chave de um documento de perfil. String LeituraLastAccessed A última data em que o documento

foi lido ou alterado.Variant of type DATE

Leitura

LastModified A última data em que o documento foi modificado.


Leitura

NameOfProfile O nome do documento de profile. String LeituraNoteID Um ID de 8 caracteres que identifica

o documento em um banco de dados.

String Leitura

ParentDataBase O banco que contem o documento. NotesDatabase LeituraParentDocument UNID

Para documentos respostas, um ID de 32 caracteres que identifica o pai de um documento.

String Leitura

ParentView A visão de onde o documento foi recuperado ou acessado.

NotesView Leitura

Responses As respostas imediatas para um Notes Document Leitura

documento. CollectionSaveMessage OnSend

Verdadeiro(true) se o documento é para ser salvo quando enviado.

Boolean Leitura

SendByAgent Verdadeiro(true) se o documento foi enviado através de script. Falso(false) se o documento foi enviado por uma pessoa.

Boolean Leitura

Signer Se o documento foi assinado, o nome da pessoa que assinou o documento.

String Leitura

SignOnSend Verdadeiro(true) se o documento é para ser assinado quando enviado.


Size O tamanho do documento em bytes incluindo arquivos anexados.

Long Leitura

UniversalID Um ID de 32 caracteres que identifica documentos em todas as réplicas de um banco de dados.

String Leitura

Verifier O nome da certificado que verifica a assinatura de um documento assinado.

String Leitura

Tabela 3.20 Métodos da classe NotesDocument

Método Descrição Dado de retorno Valor de

retorno

Append ItemValue

Cria um novo item no documento e define seu valor ou adiciona um valor a um item existente.

NotesItem O novo item

Compute With Form

Executa todos os valores padrões, transações de entrada e fórmulas de validação para os documentos usados.

Boolean Verdadeiro se todas as fórmulas executadas tiveram sucesso

CopyAll Item

Copia todos os itens de um documento para o outro.

Nenhum Nenhum

CopyItem Copia um item no documento corrente. NotesItem O novo itemCopyTo Database

Copia um documento para um banco de dados.

NotesDocument O novo documento

Create Reply Message

Cria um novo documento como resposta do documento corrente.

NotesDocument O novo documento resposta

Create RichText Item

Cria um campo de texto rico no documento.

NotesRichText Item

O novo campo de texto rico

Encrypt Criptografa o documento. Nenhum NenhumGet Attachment

Obtém o nome do arquivo anexado ao documento.

Notes Embedded Object

O arquivo atachado

GetFirst Item

Obtém o primeiro item com o nome fornecido no documento.

NotesItem O item

GetItem Obtém o valor do item do documento String para campo O valor

Value cujo nome foi fornecido. rico. Array of strings para campo texto ou lista. Array of double para números, lista de números e data/hora

GetNext Item

Obtém o próximo item cujo nome seja o mesmo do fornecido.

NotesItem O item

HasItem Verdadeiro(true) se o documento tem um item com o nome fornecido.

Boolean Verdadeiro se o item existe

Make Response

Torna o documento corrente uma resposta do fornecido.

Nenhum Nenhum

PutInFolder Põe o documento em uma pasta fornecida. Cria a pasta se não existir.

Nenhum Nenhum

Remove Exclui o documento. Boolean Verdadeiro se o documento foi excluído

Remove FromFolder

Remove o documento de uma pasta especificada.

Nenhum Nenhum

Remove Item

Exclui todos os items com um nome específico de um documento.

Nenhum Nenhum

RenderTo RTItem

Cria uma imagem de um documento e armazena esta imagem em um campo rico.

Boolean Verdadeiro se a figura foi criada

Replace ItemValue

Substitui todos os itens especificados e atribui novos valores.

NotesItem O novo item

Save Salva todas as mudanças feitas em um documento.

Boolean Verdadeiro se documento foi salvo

Send Envia um documento para os recipientes especificados.

Nenhum Nenhum

Sign Adiciona a assinatura do usuário corrente ao documento.

Nenhum Nenhum

10.1 Criando um documento

Você cria um novo documento usando tanto o método CreateDocument da classe NotesDatabase quanto o método New.

10.2 Procurando um documento

Existem muitas maneiras de achar um documento. Você pode usar métodos da classe NotesView e NotesDataBase para achar. Use métodos da NotesView para achar o seguinte:

• Achar todos os documentos de um banco de dados;

• Achar documentos baseados em seu Notes ID ou Universal ID;

• Achar um documento que satisfaz a um consulta de texto total;

• Achar um documento selecionado por uma fórmula de seleção.

Se o documento corrente foi encontrado usando um busca de texto completo, a propriedade FTSearchScore é substituída pelo resultado calculado pela pesquisa. Se o documento foi recuperado a partir de uma visão, você pode usar a propriedade ParenteView para achar a visão que contem o documento. Outra propriedade que somente é definida se o documento foi achado em uma visão, é a propriedade ColumnValues. Ela retorna uma array representando os valores que aparecem em cada coluna da visão principal para este documento.

Veja as sessões NotesView e NotesDataBase neste capítulo para mais detalhes de como achar documentos.

A classe NotesDocument também tem propriedades que deixa-o encontrar todas respostas de um documento ou seu documento principal. Nós veremos isto depois em “Trabalhando com Documentos Respostas”.

10.3 Trabalhando com propriedades de documentos

Depois de você obter um documento, você pode usar algumas das muitas propriedades da classe NotesDocument para examiná-las em detalhe. Você pode dizer se o documento acabou de ser criado usando a propriedade IsNewNote. Se o documento nunca foi salvo, a propriedade retorna verdadeiro. A propriedade Criated diz a você quando o documento foi criado. Se o documento tem sido salvo, você pode usar a propriedade LastAccessed e LastModified para ver quando foi sua última atualização. Você pode usar a propriedade IsUnread para checar se o usuário corrente tem lido o documento. Se você precisa saber qual o tamanho de um documento, a propriedade Size retorna o tamanho corrente do documento.

O NoteID e UniversalID para documentos são também válidos para você como propriedades.Você pode checar se um documento contem uma assinatura eletrônica usando a

propriedade IsSigned. Se IsSigned é verdadeiro, a propriedade Signer contem o nome da pessoa que assinou o documento, e a propriedade Verified armazena o nome do certificador usado para verificar assinatura. Se o documento não é assinado, você pode usar o método Sign para assiná-lo. O exemplo seguinte mostra como assinar um documento:


Dim s As New NotesUIWorkspace Dim ulDoc As NotesUIDocument Dim doc As NotesDocument

Set uiDoc = s.CurrentDocument

Set doc = uiDoc. Document

If (Not doc.IsSigned) then

Call doc.Sign

Call doc.Save(False, True)

Verify.Name = doc.Verifier

Messagebox(“ Documento assinado por “ & doc.Signer &

“ e verificado por “ & doc.Verifier & “.”)

Else

MessageBox( “ Documento já está assinado “ ) End If

End Sub

Se segurança é importante, você pode também encriptar o documento usando o método Encrypt. Esteja certo que a propriedade EncryptionKeys está como o nome da chave de encriptação que você quer usar antes de encriptar o documento. Você também pode checar quem tem editado o documento lendo a propriedade Authors.

CUIDADO

Encriptação em correio trabalha de forma diferente a encriptação de documentos. Se você quer enviar um documento encriptado, mude a propriedade EncyptOnSend para verdadeiro e, então, envie o documento usando o método Send.

Se você está procurando por objetos e arquivos anexados ao documento, você pode usar a propriedade HasEmbedded para checar se eles existem. Você pode obter alguns, mas não todos, objetos dentro de um documento usando a propriedade EmbeddedObjects. Use a propriedade GetAttachment para obter um arquivo anexado a partir de seu nome.

CUIDADO

A propriedade EmbeddedObjects não retorna qualquer arquivo anexado ou objeto OLE/1 criado em versões anteriores do Notes. Se você precisa obter estes objetos, use a versão NotesRichTextItem da propriedade EmbeddedObjects.

10.4 Trabalhando com documentos de perfil

Documentos de perfil surgiram na versão 4.5 do Notes. Existem documentos que você pode criar a partir de um código para armazenar itens específicos de banco de dados. Por exemplo, você pode querer armazenar alguns parâmetros que definem como e quando documentos seriam armazenados em um banco de dados. Você pode checar se um documento é um documento de perfil usando a propriedade IsProfile. Depois de você obter um documento de perfil, você pode obter seu nome a partir da propriedade NameOfProfile e sua chave usando a propriedade Key.

10.5 Criando e modificando itens de documento

Você pode usar a proprieade Items para obter uma lista de todos os itens armazenados no documento. Ela retorna uma array de objetos NotesItems e você pode examinar usando as propriedades e métodos da classe NotesItem. Você pode usar GetFirstItem para obter o primeiro item no documento com o nome que você especificou.

Se você está procurando por um item particular, você pode ver se ele existe usando HasItem. Você fornece o nome de um item e HasItem retorna verdadeiro se o documento contem este item. Você pode obter o conteúdo de um item de várias maneiras. Tanto usando GetItemValue e fornecendo o nome do item como um parâmetro, ou usando o que é conhecido como sintaxe de classe estendida, que deixa-o acessar como se ele fosse a propriedade de um documento. Por exemplo, os dois códigos a seguir obtém o conteúdo do item Quantity. Este exemplo usa GetItemValue:





Dim varQuantity As Variant



VarQuantity = doc.GetItemValue(“Quantity”);

End Sub

O exemplo seguinte faz o mesmo que o anterior mas usa sintaxe de classe estendida:





Dim varQuantity As Variant



VarQuantity = doc.Quantity;

End Sub

NOTA

Sintaxe de Classe Estendida deixa-o tratar um item como se fosse uma propriedade de um documento. O item de fato torna-se uma propriedade extra do documento. Você pode ler e alterar o item da mesma forma que as outras propriedades. Por exemplo, se o documento contem um intem chamado DocAuthor, você pode acessar seu valor usando a mesma sintaxe de uma propriedade.

DICA

GetItemValue sempre retorna uma array se o item contem somente um valor. Se o item contem um valor simples, ele é armazenado como o primeiro elemento da array.

Você pode usar AppendItemValue e ReplaceItemValue para criar um novo item ou atualizar o conteúdo de um existente. Se um item fornecido por você não existe, um novo é criado. O exemplo seguinte usa dois métodos para criar um novo item no documento:





Dim itmTitle As NotesItem

Dim itmPlace As NotesItem



Set itmTitle = doc.AppendItemValue(“Título”, “A busca do conhecimento”)

Set itmPrice = doc.ReplaceItemValue(“Preço”,50)

Call doc.Save(True,True)

End Sub

Você pode também criar um item de texto rico usando o método

CreateRichTextItem.

10.6 Usando o método ComputeWithForm

Usualmente você cria documentos para completar um formulário usando a interface de usuário do Notes. Quando você salva o documento, as fórmulas de validação de campo no formulário são computadas e, se quaisquer dos valores de campo são incorretos, você não poderá salvar o documento. Evitando estas fórmulas de validação e criando documentos em background nós podemos criar documentos que evitariam os testes de validação de campo. Se é importante checar que o documento que você tem criado da de frente com um critério de validação de campo, você pode usar o método ComputeWithForm para forçar a execução da fórmula de validação.

Isto pode ser interessante se você tem mudado a estrutura de um formulário para incluir códigos de validação e você precisa testar se os documentos existentes são válidos ainda. Você pode checar cada documento usando ComputeWithForm e atualizar aqueles que se deparam com novo critério de validação.

10.7 Copiando e excluindo itens de documento

Há dois métodos que deixa-o copiar itens entre documentos. CopyItem copia um item simples de um documento para outro enquanto CopyAllItems copia todos os itens do documento.

Para excluir um item de um documento use RemoveItem.

10.8 Trabalhando com documentos respostas

É realmente fácil achar todas as respostas imediatas para um documento. Basta usar a propriedade Response. Ela retorna uma coleção de documentos Notes contento todas as repostas do documento corrente. Se você precisa checar se o documento corrente é um documento resposta, use a propriedade IsResponse. Se ela for verdadeira então você está trabalhando com um documento resposta. Você pode, então, usar a propriedade ParentDocumentUNID para achar o Universal ID do documento pai.

Algumas vezes você precisa mudar a localização do documento em uma visão hierárquica, por exemplo, para fazer um documento resposta de outro. Use o método MakeResponse para fazer esta mudança. Você chama este método em um documento para torná-lo resposta de outro.

10.9 Movendo e copiando documentos

Além de você alterar a localização de um documento no banco de dados, você pode também copiá-lo para outro banco de dados. O método CopyToDatabase cria uma nova cópia do documento no banco de dados que você especificou.

Você pode também mover documentos entre pastas no banco de dados. Use PutInFolder para adicionar um documento a uma pasta e RemoveFromFolder para tirá-lo da pasta.

10.10 Enviando um documento

Uma das melhores características do Notes é sua forte integração com o sistema de correio. Todos os documentos são potencialmente mensagens de correio. A classe NotesDocument deixa-o explorar isto tornando muito fácil enviar seus documentos. Você pode enviar qualquer documento usando o método Send. Simplesmente forneça uma lista de destinatários, chame o método Send, e a mensagem será enviada para os destinatários. Se o documento possui um campo SendTo, então sua lista de destinatários é ignorada e o

documento é enviado para os destinatários listados no campo SendTo. Se você marcar a propriedade SaveMessageOnSend, o documento é automaticamente salvo depois de enviado. Você pode também especificar algumas opções de envio tal como SignOnSend e EncryptOnSend.

Um método útil para usar quando você está enviando documentos é RenderToRTItem. Ele cria uma imagem do documento e coloca-o em um campo de texto rico.

Você pode criar uma resposta ao documento corrente usando CreateReplyMessage. Este método cria um novo documento que é formatado como uma resposta do original. Isto pode ser útil para gerar e enviar automaticamente notificações quando você está desenvolvendo uma aplicação de workflow. Por exemplo, você pode reconhecer automaticamente o recebimento de um formulário de reclamação de despesas.

10.11 Salvando e excluindo um documento

Nenhuma das alterações feitas em um documento tem efeito até ele ser salvo. Se você não salvou seu documento, todas as mudanças são perdidas quando o banco de dados for fechado. Use o método Save para salvar suas mudanças. Você usa Save com dois ou três parâmetros. Defina o primeiro atributo para verdadeiro(true) para salvar o documento só se mais alguém tem editado uma copia dele enquanto você trabalha com ele. Se você usa este parâmetro, sua copia do documento sobrepõe a original. Se você define o primeiro parâmetro para falso(false), o que acontece quando você salva o

documento é decidido pelo segundo parâmetro.

Quando o segundo parâmetro é verdadeiro(true), seu documento torna-se uma resposta do original. Quando falso(false), o documento não é salvo e suas mudanças são descartadas.

O terceiro parâmetro, opcional, é usado par indicar se o documento salvo deve ser marcado como leitura. Defina este parâmetro para verdadeiro(true) para marcá-lo como leitura ou falso(false) para marcá-lo como não leitura.

Você pode remover um documento de um banco de dados usando o método Remove.

11 NOTESFORM

A classe NotesForm deixa-o examinar e trabalhar com propriedades de formulário. Você pode também usar a classe para excluir um formulário de um banco de dados. As propriedades e métodos da classe são mostrados nas tabelas 3.21 e 3.22 .

Tabela 3.21 Propriedades da classe NotesForm

Propriedade Descrição Tipo de Dado

Usado

Aliases O aliases de um formulário. Array of strings

Leitura

Fields Os nomes dos campos no formulário. Array of string

Leitura

FormUsers Os nomes dos usuários que podem usar o formulário (O conteúdo do campo $FormUsers).

Array of strings

Leitura/ Gravação

IsSubForm Verdade se o formulário é um subformulário. Boolean LeituraName O nome do formulário. String Leitura

Protect Readers

Torne-o verdadeiro(true) para proteger o item $Readers durante a replicação.

Boolean Leitura/ Gravação

ProtectUsers Torne-o verdadeiro(true) para proteger o item $FormUsers durante a replicação.

Boolean Leitura/ Gravação

Readers O nome dos usuários que podem ler o formulário(O conteúdo do campo $Readers).

Array of strings

Leitura/ Gravação

Tabela 3.22 Métodos da classe NotesForm

Método Descrição Tipo de Dado Usado

Remove Exclui um formulário de um banco de dados.

Nenhum Nenhum

12 NOTESITEM

A classe NotesItem deixa-o trabalhar com o conteúdo de um documento. Quando você entra com um valor em um campo no formulário e salva o documento, Notes armazena o valor que você entra como um item no documento. NotesItem deixa-o examinar e modificar estes itens. Você pode usar as propriedades e métodos da classe NotesItem para fazer o seguinte:

• Examinar as propriedades dos itens;• Criar itens em um documento;• Modificar itens em um documento;• Exclui itens.

Veja as tabelas 3.23 e 3.24 que mostram as propriedades e métodos da classe NotesItem.

Tabela 3.23 propriedades da classe NotesItem


DateTime Value

Somente para itens data/hora. Um objeto NotesDateTime representando o item.

NotesDate Time Leitura/ Gravação

IsAuthors Verdadeiro(true) se o item é um autor. Boolean LeituraIsEncrypted Verdadeiro(true) se o item está

encriptado.Boolean Leitura

IsNames Verdadeiro(true) se o item é um nome. Boolean LeituraIsProtected Verdadeiro(true) se o item pode ser

alterado por um usuário que possua pelo menos acesso editor.

Boolean Leitura

IsReaders Verdadeiro(true) se o item é um leitor. Boolean LeituraIsSigned Verdadeiro(true) se o item contêm uma

assinatura eletrônica.Boolean Leitura

IsSummary Verdadeiro(true) se o item é um sumário. Boolean LeituraLastModified A data de última modificação do item. Variant of type

dateLeitura

Name O nome do item. String Leitura

Parent O documento que contêm o item. Notes Document LeituraSaveToDisk Verdadeiro(true) se o item deveria ser

salvo no disco quando o documento que o contêm é salvo.

Boolean Leitura

Text A representação textual de um item. Lista de itens são separados por ponto-e-vírgula.

String Leitura

Type O tipo do item. Integer constant LeituraValueLength O tamanho, em bytes, do item . Integer LeituraValues Os valores armazenados no item. String para itens

richtext . Array of strings para itens texto ou lista de texto. Array or double para números, listas de números ou itens data/hora

Leitura/ Gravação

Tabela 3.24 Métodos da classe NotesItem

Método Descrição Tipo de Dado de Retorno

Valor de Retorno

Abstract Abrevia o texto do item. String Texto abreviado

AppendTo TextList

Para um item de lista de texto, adiciona um outro valor no final da lista.

Nenhum Nenhum

Contains Para itens contento listas, verifica se o valor fornecido por você está na lista. Pode ser usado em listas do com números, textos e datas.

Boolean Verdadeiro se o valor está na lista

CopyItem ToDocument

Copia o item para um documento. NotesItem O novo item

New Cria um novo item. NotesItem O novo item

Remove Deleta o item do documento. Nenhum Nenhum

12.1 Examinando as propriedades de um item

Use a propriedade Name para achar o nome de um item. Você pode verificar que tipo de item você está trabalhando examinando sua propriedade Type. Por exemplo, Type

deixa-o saber se um item é do tipo texto. Você pode verificar mais sobre o item usando IsNames, IsAuthors, e IsReaders para ver se ele é um desses tipos especiais. A propriedade LastModified retorna a data na qual o item foi pela última vez modificado.

Você pode checar a segurança de um item usando IsEncrypted, IsProtected e IsSigned.

12.2 Criando e modificando itens

Use o método New para criar novos itens no documento. Você fornece o documento, o nome do novo item e seu valor inicial. Se você está criando um item do tipo texto, você pode opcionalmente definí-lo como Names, Readers, ou Authors. Você também pode criar um novo item copiando um item existente de um documento para outro usando CopyItemToDocument.

Você pode ler ou modificar o conteúdo de um item usando a propriedade Values. Quando o item é lido, Values retorna o conteúdo do item no seu formato apropriado. Da mesma forma, quando você usa Values para modificar o conteúdo de um item, você deve fornecer o novo valor no formato correto. Você pode, alternativamente, usar a propriedade Text para converter o valor de um item para sua representação textual.

Se você está trabalhando com um item do tipo lista de texto, você pode usar o método AppendToTextList para adicionar novos valores ao final da lista.

Finalmente, você pode usar o método Abstract para abreviar o conteúdo de um item texto. Você especifica o número máximo de caracteres a retornar e informação de como abreviar o texto. O método retorna o conteúdo abreviado do item.

12.3 Excluindo itens

Para excluir um item de um documento, use o método Remove. Lembre de salvar o documento para que suas alterações tenham efeitos.

13 NotesRichTextItem

A classe NotesRichTextItem deixa-o criar e modificar campos de texto rico nos documentos. Você pode fazer o seguinte:

• Adicionar texto, formatar caracteres e criar um link a um campo de texto rico;

• Combinar campos de texto rico;

• Importar um arquivo em um campo de texto rico;

• Achar os objetos e arquivos que estão contidos em um campo de texto rico.

As propriedades da classe NotesRichTextItem são listadas na tabela 3.25 e os seus métodos na tabela 3.26 .

Tabela 3.25 Propriedades da classe NotesRichTextItem


Embedded Objects

Todos os objetos OLE, ActiveX e arquivos do item de texto rico.

Array of NotesEmbedded Objects

Leitura

Tabela 3.26 Métodos da classe NotesRichTextItem

Método Descrição Tipo de Dado Usado

AddNewLine Adiciona uma ou mais linhas ao item de texto rico.

Nenhum Nenhum

AddTab Adiciona um ou mais caracteres de tabulação ao item de texto rico.

Nenhum Nenhum

AppendDoc Link

Dado um banco de dados, uma visão ou documento, cria um link para o objeto e adiciona-o ao item de texto rico.

Nenhum Nenhum

AppendRT File

Dado um arquivo no formato de texto rico, adiciona seu conteúdo ao item de texto rico.

Nenhum Nenhum

AppendRT Item

Adiciona um item de texto rico a outro.

Nenhum Nenhum

AppendText Adiciona o texto fornecido ao item de texto rico.

Nenhum Nenhum

EmbedObject

Dado o nome de um arquivo ou aplicação, cria o objeto, um link ou um arquivo anexado e armazena-o no campo de texto rico.

NotesEmbedded Object

O novo objeto criado

Get Embedded Object

Dado o nome de um objeto, link ou arquivo anexado a um item de texto rico, retorna o NotesEmbeddedObject correspondente.

NotesEmbedded Object

Object

GetFormattedText

Retorna o conteúdo do item de texto rico como uma string.

String O texto do item de texto rico

New Cria um item richtext. NotesRichText Item

O novo item de texto rico criado

13.1 Criando e modificando um item richtext

Como em muitas classes, você pode criar objetos na classe NotesRichTextItem de várias formas. Se você tem um objeto NotesDocument, você pode usar seu método CreateRichItem para criar um novo objeto NotesRichText. Alternativamente, você pode usar New na classe NotesRichTextItem.

Para achar e usar campos de texto rico que já existe no documento, use os métodos GetFirstItem e GetNextItem da classe NotesDocument. O seguinte código mostra como

achar o item chamado richtext body:


Dim varItem As Variant

‘ . . . Set value of doc . . .

set varitem = doc.GetFirstItem(“Body”)

If (varItem.Type=RICHTEXT) then

‘ Então se é um texto de texto rico, você pode usar o método NotesRichTextItem

End If

Quando você cria ou acha um item de texto rico, você pode adicionar texto a ele usando o método AppendText. Você pode também adicionar qualquer número de tabulações e novas linhas usando AddTab e AddNewLine, ou adicionar o conteúdo de um campo de texto rico a outro usando AppendRTItem.

Você pode criar objetos ou arquivos anexados em um campo richtext usando EmbedObject.

CUIDADO

Você pode anexar arquivos em qualquer plataforma Notes, mas você somente pode criar objetos linkados em uma plataforma que suporta OLE.

Um dos métodos mais úteis suportado pela classe é o método AppendDocLink. Este método deixa-o criar qualquer dos três tipos de links do Notes ( link de banco de dados, link de visão e link de documento) e adicioná-lo ao campo de texto rico. Isto é bom para criar documentos de sumário. Por exemplo, você pode criar um código que busca novos documentos em todos os seus banco de dados e envia para você um documento com um resumo contento links de banco de dados para os bancos de dados que você checou.

13.2 Lendo um item richtext

Você pode obter o texto de um item de texto rico de algumas formas. Se você quer reformatar o texto, você pode usar o método GetFormattedText. Ele lhe dá a opção de remover quaisquer caracteres tab e deixar sem espaços extras. Se você quer apenas o texto e não está preocupado com seu formato, use o método Text.

Você pode obter o nome de um objeto dentro de um campo de texto rico usando GetEmbeddedObject. Você fornece o nome do objeto e o método retorna um NotesEmbeddedObject representando o objeto. Você pode então usar as propriedades e métodos da classe NotesEmbeddedObject para trabalhar com objetos.

14 NotesEmbeddedObject

A classe NotesEmbeddedObject pode representar um arquivo anexado, um objeto embutido ou um objeto linkado. Você usa esta classe para fazer o seguinte:

• Achar a classe OLE e propriedades de um objeto embutido;

• Achar os verbos OLE que o objeto suporta;

• Ativar quaisquer destes verbos OLE.

As propriedades da classe são mostradas na tabela 3.27 e seus métodos são mostrados na tabela 3.28

Tabela 3.27 Propriedades da classe NotesEmbeddedObject


Class O nome da aplicação que criou objeto.

String Leitura

FileSize O tamanho, em bytes, do objeto. Long Leitura

Name O nome usado para referenciar o objeto.

String Leitura

Object O OLE handle para o objeto. Variant Leitura

Parent O item de texto rico que contêm o objeto.

NotesRichTextItem Leitura

Source Para arquivos anexados, o nome do arquivo. Para outros tipos de objetos, um nome interno usado pelo Notes.

String Leitura

Type Mostra o tipo do objeto. IntegerConstant Leitura

Verbs Para objetos OLE2, os verbos suportados pelo objetivo

Array of string Leitura

Tabela 3.28 Métodos da classe NotesEmbeddedObject


Valor de Retorno

Activate Somente para objetos embutidos ou linkados, carrega o objeto e ativa sua aplicação de servidor OLE.

Variant -

DoVerb Somente para objetos embutidos, executa o verbo fornecido.

Nenhum Nenhum

ExtractFile Somente para arquivos anexados, copia o arquivo anexado para o nome de arquivo fornecido.

Nenhum Nenhum

Remove Exclui o objeto embutido, linkado ou o arquivo anexado.

Nenhum Nenhum

14.1 Criando um objeto embutido

Você cria objetos embutido em um campo de texto rico de um documento usando o método EmbedObject da classe NotesRichTextItem.

14.2 Achando um objeto embutido

Você pode achar todos os objetos embutidos ou linkados em um documento usando a propriedade EmbeddedObject da classe NotesDocument. Se você precisa somente olhar um campo particular, você pode usar a propriedade EmbeddedObjects, da classe NotesRichTextItem, para obter todos os objetos embutidos no campo. Ambas as propriedades retornam uma array de NotesEmbeddedObject. Quando você sabe o nome do campo de texto rico e o nome do objeto, use GetEmbeddedObject no item para obter o objeto.

14.3 Obtendo as propriedades de um objeto embutido

Depois de você ter um objeto, você pode usar as propriedades nesta classe para obter seus detalhes. Use Type para checar se o objeto é um objeto embutido, linkado ou arquivo anexado.

Então, para objetos embutidos você pode usar Class para obter o nome OLE da aplicação que criou o objeto. Use Name para obter o nome do objeto. Se o objeto foi criado usando a caixa de diálogo “Notes Created Object”, este é o nome que aparece na lista de tipos de objetos na caixa de diálogo. Objetos obtém o erro de objeto OLE e verbos obtém uma lista de todos os verbos OLE que o objeto suporta. Para arquivos anexados, use Source para obter o nome do arquivo . Para todos os tipos de objetos, a propriedade FileSize dá a você o tamanho em bytes de todos os objetos e arquivos anexados.

14.4 Ativando um objeto embutido

Você pode carregar um objeto OLE embutido ou linkado usando o método Active. Você pode opcionalmente mostrar ou ocultar a interface do usuário da aplicação de servidor OLE. O método retorna o handle de OLE para o objeto, e você pode então acessar o método do objeto.

Você pode também executar qualquer dos verbos suportados pelo objeto usando o método DoVerb.

14.5 Extraindo o arquivo anexado

Se você está tratando com um objeto de arquivo anexado, você pode copiar o arquivo anexado para o disco usando ExtractFile. Você fornece um caminho para o arquivo e o método copia o arquivo para o disco.

14.6 Excluindo um objeto embutido

Você exclui um objeto embutido chamando o método Remove. Da mesma forma com os outros métodos que exclui itens de um documento, você deve salvar o documento para que suas alterações tenham efeito.

15 NotesDocumentCollection

A classe NotesDocumentCollection deixa-o trabalhar com subconjuntos de documentos em um banco de dados. Você tem muita flexibilidade em como selecionar os documentos na coleção. Por exemplo, você pode obter o seguinte:

• Todos os documentos de um banco de dados;• Usar uma consulta de texto completo para achar estes documentos;• Usar uma fórmula para achar estes documentos;• Achar documentos que não foram processados por um agente;• Todas as respostas de um documento.

Veja a tabela 3.29 para ver as propriedades da classe e a tabela 3.30 para ver seus métodos.

Tabela 3.29 Propriedades da classe NotesDocumentCollection


Count O número de documentos na coleção.

Long Leitura

IsSorted Se a coleção está ordenada. Somente as coleções produzidas por uma consulta de texto completo serão ordenadas.

Boolean Leitura

Parent O banco de dados que contém a coleção.

NotesDatabase Leitura

Query A consulta usada para selecionar a coleção que foi produzida por uma busca.

String Leitura

Tabela 3.30 Métodos da classe NotesDocumentCollection


Valor de Retorno

GetFirst

Document

Obtém o primeiro documento da coleção.

NotesDocument O primeiro documento

GetLast Document

Obtém o último documento da coleção.

NotesDocument O último documento

GetNext Document

Obtém o próximo documento da coleção em relação ao atual.

NotesDocument O próximo documento

GetNth

Document

Obtém um documento na posição do índice dado.


GetPrev

Document

Obtém o documento anterior ao atual da coleção.

Notes Document O documento

Coleções não são tão suficientes como visões para acessar documentos, porque coleções devem ser criadas por você, enquanto visões já estão cosntruídas no banco de dados. Então, se você pode obter os documentos que você quer usar através de visões, use-a ao invés de coleções.

15.1 Criando uma coleção

Você usa propriedades e métodos em um banco de dados Notes e classes NotesDocument para obter uma coleção de documentos. Uma coleção simples seria todos os documentos de um banco de dados, usando a propriedade AllDocument da classe NotesDocument. Você pode restringir os documentos que estão inclusos na coleção usando tanto o método FTSearch como Search da classe NotesDatabase. Você fornece o método FTSearch com uma consulta de texto completo e o número máximo de documentos para serem procurados, e o método retorna a coleção de todos os documentos que satisfazem a consulta. Por exemplo, para achar os 10 primeiros documentos contento as palavras Holly e Backen, use o exemplo abaixo:




Dim coll As NotesDocumentCollection


Set coll = db. FTSearch(|”Holly” & “Bracken”|, 10)

End Sub

Para achar todos os documentos que satisfazem a consulta, especifique 0 como o número de documentos a serem retornados.

DICA

Use a barra vertical para delimitar a string de busca. Se você usa aspas como delimitador de strings, você tem que duplicar qualquer aspas na string de busca, que logo se torna difícil de ler.

Use o método Search quanto quiser selecionar documentos usando uma fórmula de seleção. Por exemplo, para selecionar todos os documentos do servidor no banco de dados corrente que foram modificados na última semana, use o seguinte:



Dim coll As NotesDocumentCollection

Dim dtLastWeek As New NotesDateTime( “Today”)


Call dt.LastWeek.Adjustday(-7)

Set coll = db. Search(|Form = “Server”|, dtLastWeek,0)

End Sub

Se você está usando um agente para acessar a coleção, você pode usar a propriedade UnprocessedDocuments ou os métodos UnprocessedFTSearch e UnprocessedSearch para limitar a coleção incluindo somente aqueles documentos que o documento considera não processado.

Se você usa um dos métodos de busca de texto completo para criar uma coleção, os documentos são armazenados com os documentos mais relevantes primeiro. Se você precisa checar se a coleção está ordenada, use a propriedade IsSorted para verificar.

15.2 Achando documentos em uma coleção

Depois de ter uma coleção, você pode usar a propriedade Count para checar quantos documentos existem na coleção. Você pode refinar os documentos na coleção executando uma consulta de texto completo nos documentos da coleção. Use FTSearch para especificar a consulta e o método modifica a coleção para conter somente estes documentos que atendem a consulta.

Você tem muitos métodos de achar documentos em uma coleção. Você pode usar GetFirstDocument e GetNextDocument para percorrer os documentos. Se você quiser percorrer os documentos da coleção de forma decrescente, use GetLastDocument e GetPrevDocument. Você pode obter um documento específico usando GetNthDocument.

15.3 Trabalhando com documentos na coleção

A partir da versão 4.5 do Notes, foi acrescentado muitos métodos que você pode usar para trabalhar com coleções de documentos. Você pode adicionar todos os documentos da coleção em uma pasta específica usando o método PutAllInFolder, ou excluí-los usando o método RemoveAllFromFolder. Você pode excluir todos os documentos de uma coleção usando RemoveAll. Se você quiser adicionar ou atualizar um item específico em todos documentos de uma coleção, use o método StampAll. Você fornece o nome do item e seu valor novo, e StampAll atualiza-o em todos documentos. Se o item não existe, StampAll adiciona-o na coleção de documentos. Quando você está trabalhando com agentes, você pode usar UpdateAll para marcar todos os documentos da coleção que tenham sido processados pelo agente.

16 NotesAgent

Agentes deixam-no automatizar tarefas no Notes tal como arquivar documentos, enviar mensagens de correio ou rotear(definir rotas para) documentos dentro de um sistema de workflow. Você pode criar agentes compartilhados como um projetista de banco de dados e torná-los disponíveis para usuários do seu banco de dados. Você pode também criar agentes pessoais para ajudar tarefas de rotinas automáticas.

NOTA

Você deve ter pelo menos acesso de designer de um banco de dados para poder criar agentes compartilhados. Para criar agentes pessoais no banco de dados, a opção “Create personal agents in the ACL” deve estar selecionada para seu nome ou para o grupo que você faz parte. No caso de bancos de dados no servidor, você deve estar incluído em um grupo de pessoas que podem criar agentes pessoais no servidor. Veja “Agent Manager Restriction” na ajuda do servidor para detalhes sobre como criar agentes pessoais.

Você pode usar a classe NotesAgent para examinar as propriedades de um agente ou para excluí-lo de um banco de dados.

As propriedades da classe NotesAgent são listadas na tabela 3.31 e seus métodos são mostrados na tabela 3.32.

Tabela 3.31 Propriedades da classe NotesAgent


Comment O comentário associado ao agente. String Leitura

Common Owner

O nome comum da pessoa que por último editou o agente.

String Leitura

IsEnabled Verdadeiro(true) se o agente está abilitado.

Boolean Leitura

IsPublic Verdadeiro(true) se o agente está disponível para todos os bancos de dados dos usuários.

Boolean Leitura

LasRun A última data na qual o agente foi executado.


Leitura

Name O nome do agente. String Leitura

Owner O nome completo da pessoa que por último editou o agente.

String Leitura

Parent O banco de dados onde o agente está armazenado.


Query O texto da consulta usado para selecionar os documentos onde o agente executa.

String Leitura

ServerName Para agentes no servidor, o nome completo do servidor onde o agente executa. Para agentes locais, o nome completo do usuário corrente.

String Leitura

Tabela 3.32 Métodos da classe NotesAgent


Valor de Retorno

Remove Exclui o agente do banco de dados Nenhum Nenhum

Run Executa um agente Nenhum Nenhum

17 NotesACL

A classe NotesACL representa a lista de controle de acesso para um banco de dados. Você pode usar a classe NotesACL para fazer o seguinte:

• Criar novas entradas na ACL;

• Examinar entradas existentes na ACL;

• Modificar ACL;

• Adicionar, excluir ou renomear regras da ACL.

Veja a tabela 3.33 para as propriedades da classe. Os métodos da mesma estão na tabela 3.34.

Tabela 3.33 Propriedades da classe NotesACL


Parent O banco de dados que contém a ACL.


Roles Todas as regras definidas na ACL. Array of strings Leitura

Tabela 3.34 Métodos da classe NotesACL


Valor de Retorno

AddRole Dado o nome da regra, adiciona a regra a ACL.

Nenhum Nenhum

Create ACL Entry

Dado uma pessoa, grupo ou nome de servidor e um nível de acesso, cria uma nova entrada na ACL.

NotesACLEntry A nova entrada na ACL

DeleteRole Dado o nome da regra, exclui a função da ACL.

Nenhum Nenhum

GetEntry Dado uma pessoa, grupo, ou nome de servidor, acha a entrada correspondente na ACL.

NotesACL A entrada na ACL para uma pessoa, grupo ou servidor

GetFirstEntry

Acha a primeira entrada na ACL NotesACLEntry A primeira entrada na ACL

GetNextEntry

Dada qualquer entrada na ACL, acha a próxima.

NotesACLEntry A próxima entrada na ACL

RenameRole Dado o nome da regra, acha a regra e a renomea.

None None

Save Salva alterações feitas na ACL None None

17.1 Criando uma entrada na ACL

O método CreateACLEntry deixa-o criar uma nova entrada na ACL para uma pessoa, grupo ou servidor. Você especifica o nome e o nível que você quer adicionar e o método cria uma nova entrada na ACL.

17.2 Achando entradas na ACL

Você pode obter uma entrada específica na ACL usando o método GetEntry. Você fornece o nome da pessoa, grupo ou servidor e o método retorna-lhe um objeto contento os detalhes para este nome. Você, então, usa a propriedade NotesACLEntry para examinar ou modificar a entrada. Você pode também percorrer por todas as entradas da ACL usando GetFirstEntry e GetNextEntry.

17.3 Modificando a ACL

A partir da versão 4.5 do Notes foi possível fazer modificações na ACL: Forçando uma consistente ACL por todas as réplicas do banco de dados. Altere a propriedade UniformAccess para verdadeiro(true) para fazer isso.

17.4 Modificando Regras

Você pode achar todas as regras definidas na ACL usando a propriedade Role. Você pode também adicionar, renomear e excluir regras da ACL usando AddRole, RenameRole, e DeleteRole.

17.5 Salvando suas alterações

Quaisquer mudanças que você tenha feito em uma ACL só são efetivadas quando você salva o objeto NotesACL usando o método Save. Se você fechar o banco de dados antes de usar o método Save, suas alterações são perdidas.

18 NotesACLEntry

A classe NotesACLEntry representa uma entrada individual na ACL para o banco de dados. Você pode usar a classe NotesACLEntry para fazer o seguinte:

• Adicionar e excluir nomes na ACL;

• Mudar algumas das ações que o usuário pode executar no banco de dados;

• Mudar as regras atribuídas a um nome na ACL.

Veja a tabela 3.35 e a tabela 3.36 para as propriedades e métodos da classe.

Tabela 3.35 Propriedades da classe NotesACLEntry


CanCreate

Documents

Verdadeiro(true) se a entrada da ACL pode criar documentos no banco de dados.


CanCreate PersonalAgent

Verdadeiro(true) se a entrada da ACL pode criar agentes pessoais no banco de dados.


CanCreate PersonalFolder

Verdadeiro(true) se a entrada da ACL pode criar pastas pessoais no banco de dados.


CanDelete Documents

Verdadeiro(true) se a entrada da ACL pode excluir documentos do banco de dados.


Level O nível de acesso para esta entrada da ACL.

Integer Constant Leitura Gravação

Name O nome associado a entrada da ACL. String Leitura Gravação

Parent A ACL que contém a entrada. NotesACL Leitura

Roles As regras que são definidas para esta entrada da ACL.

Array of strings Leitura

Tabela 3.36 Métodos da classe NotesACLEntry


Valor de Retorno

DisableRole

Dado o nome da regra, remove a regra da entrada na ACL.

Nenhum Nenhum

EnableRole Dado o nome da regra, adiciona a regra a entrada da ACL.

Nenhum Nenhum

IsRole Enabled

Dado o nome da função, checar se a entrada da ACL tem a regra abilitada.

Boolean Verdadeiro se a função está abilitada

New Cria uma nova entrada na ACL. NotesACLEntry A nova entrada criada

Remove Exclui a entrada da ACL fornecida a partir da ACL.

Nenhum Nenhum

18.1 Criando e excluindo entradas da ACL

Em adição ao uso do método CreateACLEntry da classe NotesACL, você pode usar New para criar novas entradas na ACL. Por exemplo, o código de botão seguinte cria uma

nova entrada na ACL para o grupo SupportTeam e dá o acesso de leitura do grupo para o banco de dados:




Dim acl As NotesACL


Set acl = db.ACL

Dim aclGroup As New NotesACLEntry(acl, “SupportTeam”, ACLLEVEL_READER)

Call acl.Save

End Sub

Se você precisa excluir uma entrada de uma l ACL, use o método Remove.

18.2 Modificando uma entrada da ACL

Você pode achar o nome associado a uma entrada da ACL usando a propriedade Name e o nível de acesso corrente usando a propriedade Level.

Você pode examinar ou modificar as ações que estão disponíveis para a entrada da ACL usando as 4 propriedades seguintes: CanCreateDocuments, CanCreatePersonalAgent, CanCreatePersonalFolder e CanDeleteDocuments. As propriedades correspondem a “Create documents “, “Create personal agents”, “Create personal folders” e “Delete documents” de uma ACL.

18.3 Modificando Regras

A classe NotesACLEntry contém um conjunto de métodos e funções similares a classe NotesACL para trabalhar com regras. Como você esperaria, os métodos na classe NotesACLEntry somente se referenciam as regras para entrada que você está trabalhando. Por exemplo, a propriedade Roles lista as regras que estão abilitadas para a entrada da ACL corrente. Você pode adicionar a entrada corrente uma regra, usando EnableRole ou removê-la usando DisableRole. Use IsRoleEnabled para testar se a regra específica está abilitada para a entrada corrente.

18.4 Salvando suas mudanças

Quaisquer mudanças que você tenha feito em uma entrada da ACL só são efetivadas quando você chama o método Save no objeto pai NotesACL. Se você fechar o banco de dados antes de usar o método Save, suas alterações serão perdidas.

19 NotesLog

A classe NotesLog deixa-o informado do que seu script está fazendo. Você tem muitas opções para gravar o progresso do seu código. Você pode registrar mensagens para um banco de dados Notes que é útil quando você quer se manter um histórico do que o seu script tem feito. De forma alternativa, você pode armazenar mensagens em um memo de correio e automaticamente enviar o memo quando seu script tiver terminado o que estava fazendo. Isto é útil para alertar pessoas quando um script tem alguma coisa útil para lhes dizer, como “ Eu sei que deveria copiar todos estes documentos na noite passada, mas estava tarde, o servidor estava trabalhando lentamente e ....” Você pegou a idéia. Uma terceira opção, se seu script está executando localmente, é escrever suas mensagens de log para um arquivo. Para scripts que são agentes, você tem uma escolha adicional. Cada agente tem um log associado a ele e você pode escrever mensagens para o log. Você pode mostrar o log para um agente selecionando o agente e então selecionar o item de menu Agent – Log .

Você pode usar a classe NotesAgent para fazer o seguinte:

• Abrir um banco de dados, correio ou arquivo de log;

• Registra ações ou erros para o log;

• Envia eventos Notes na rede

Veja a tabela 3.37 para uma lista de propriedades da classe NotesLog e a tabela 3.38 para uma lista de métodos.

Tabela 3.37 Propriedades da classe NotesLog


LogActions Verdadeiro(true) se as ações devem ser registradas.

Boolean Leitura

LogErrors Verdadeiro(true) se os erros devem ser armazenados.

Boolean Leitura

NumActions O número de ações que têm sido registradas.

Integer Leitura

NumErros O número de erros que foram registrados.

Integer Leitura

OverWriteFile Se o log está sendo gravado em um arquivo. Diz se um arquivo de log deve ser sobrescrevido com este log ou adicionado este log a ele.


ProgramName

O nome que identifica o script e é usado para identificar as entradas do log.

String Leitura Gravação

Tabela 3.38 Métodos da classe NotesLog


Valor de Retorno

Close Fecha um log. Nenhum Nenhum

LogAction Escreve uma ação de mensagem no log.

Nenhum Nenhum

LogError Escreve uma mensagem de erro no log.

Nenhum Nenhum

LogEvent Gera um evento Notes. Nenhum Nenhum

New Cria um novo log. NotesLog O novo log criado

OpenAgent Log

Abre um log de um agente. Nenhum Nenhum

OpenFile Log

Dado um nome de um arquivo, abre o arquivo e escreve qualquer ação subsequente ou mensagens de erro no arquivo.

Nenhum Nenhum

OpenMail Log

Cria um novo mail memo endereçado para o destinatário que você especificou. Escreve qualquer ação subsequente ou mensagem de erro ao memo e envia-o quando o log é fechado.

Nenhum Nenhum

OpenNotesLog

Dado um nome de servidor e arquivo, abre o banco de dados de log específico. Escreve qualquer ação subsequente ou mensagens de erro ao banco de dados.

Nenhum Nenhum

19.1 Criando um log

Você cria um novo log usando tanto o método CreateLog da classe NotesSession quanto o método New. Em cada método, você fornece um nome para identificar o novo log. Você pode acessar este nome mais tarde usando a propriedade ProgramName.

19.2 Abrindo um log

Você tem 4 opções para o tipo de log que você quer criar, e cada tipo de log tem um método para abrí-lo. OpenNotesLog abre um banco de dados específico. O banco de dados deve ser baseado no modelo StdR4AgentLog que vem com o Notes. Se você olha para a estrutura do modelo, você vê que ele é projetado para armazenar uma entrada de log. Você pode criar um banco de dados de log para todos seus agentes ou um banco de dados para cada agente. Quando você registra mensagens no banco de dados, Um novo documento de entrada de log é criado para cada mensagem.

DICA

Se você está indo abrir um banco de dados de log a partir de um script em um servidor, esteja certo que o banco de dados de log está no mesmo servidor. Scripts que executam em um servidor não podem abrir banco de dados em outro servidor.

Para abrir um log de correio, use OpenMailLog. Você fornece o método com os nomes das pessoas ou grupos para receber o mail memo e opcionalmente a linha de subject para o memo. Quaisquer entradas de log que você escreve são armazenadas no mail memo até que você feche o log. O mail memo é então enviado para a lista de destinatários. O terceiro método de abrir um log é OpenFileLog. Com este método, você fornece o caminho completo do arquivo onde você quer armazenar suas mensagens de log. O último método é OpenAgentLog e você usa este método para registrar mensagens ao log associado a um agente.

19.3 Especificando o que registrar

Por padrão, ações e erros são armazenados no log. Se você não quer registrar uma dessas, defina a propriedade LogAction ou LogErrors como falso. Você pode checar quantas mensagens e erros foram registrados até aqui lendo as propriedades NumActions e NumErros respectivamente. Estas propriedades são úteis se você quer limitar o tamanho do log especificando o número de entradas no log. Se você está usando um arquivo de log, você pode definir OverwriteFile como verdadeiro(true) para sobrescrever qualquer arquivo existente com o mesmo nome do seu arquivo de log. Se OverwriteFile é falso, suas mensagens são adicionadas ao arquivo de log.

19.4 Escrevendo no log

Quando você quer escrever uma mensagem de log ao seu log, chame um destes métodos: LogAction, LogError ou LogEvent.

O método LogAction faz uma das seguintes coisas, dependendo do tipo de log que você abriu:

• Se você está registrando em um banco de dados, LogActions cria um novo documento de entrada no banco de dados contento o texto que você forneceu no método;

• Se você está usando um log de correio, o método escreve a data e hora corrente seguido por sua mensagem de log no corpo do mail memo;

• Para arquivos de log, LogAction escreve a data e hora corrente seguido por sua mensagem de log na próxima linha do arquivo.

LogError é semelhante, exceto que você fornece o método com um código de erro e uma descrição, que é escrita no log da mesma forma como em LogAction.

LogEvent é diferente porque ele envia uma mensagem de evento pela rede. Você pode usar LogEvent para enviar avisos ao software de gerenciamento de sistema tal como NotesView.

19.5 Fechando um log

Quando você encerra suas mensagens de registro, você fecha o log usando o método Close. Se você está usando um log de correio, o este método envia o mail memo para seus destinatários.

20 NotesDateTime

Uma das coisas que geram mais confusão trabalhando com data e hora no LotusScript é que você quer tratar com dois tipos diferentes de formatos para data-hora: o formato date-time do Notes e o formato date-time do LotusScript. O objeto NotesDateTime representa uma data e hora no formato Notes. Ele tem um componente data, hora, zona e ajuste de hora além de armazenar hora com precisão de centésimos de segundos. Em contraste com ele, a variante de data-hora do LotusScript que somente tem componentes data e hora além armazenar hora com precisão de segundos.

Quando você obtém o valor data-hora de um documento Notes, você obtém-o como um objeto NotesDateTime. Você pode usar o este objeto para fazer o seguinte:

• Converter entre o formato de data-hora do Notes e LotusScript;

• Converter entre o formato de data-hora do Notes em uma string;

• Modifica o componente data-hora do formato Notes.

Veja a tabela 3.39 para as propriedades da classe e a tabela 3.40 para ver seus métodos

Tabela 3.39 Propriedades da classe NotesDateTime


GMTTime A data-hora convertida para o horário de Greenwich.

String Leitura

IsDST Verdadeiro(true) se o computador executa o código que foi definido para observar se os ajustes de hora estão tendo efeito.

Boolean Leitura

LocalTime A data-hora da zona local. String Leitura Gravação

LSGMTime A data-hora convertida para o horário de Greenwich.


Leitura

LSLocalTime A data-hora da zona local. Variant of type DATE

Leitura

TimeZone A zona corrente. Integer Leitura

ZoneTime A data-hora ajustada para as propriedades TimeZone e IsDST e retornada como uma string.

String Leitura

Tabela 3.40 Métodos da classe NotesDateTime


Valor de Retorno

AdjustDay Adiciona ou subtrai o número de dias que você especificou na data-hora.

Nenhum Nenhum

AdjustHour Adiciona ou subtrai o número de horas que você especificou na data-hora.

Nenhum Nenhum

Adjust Minute

Adiciona ou subtrai o número de minutos que você especificou na data-hora.

Nenhum Nenhum

Adjust Month

Adiciona ou subtrai o número de meses que você especificou na data-hora.

Nenhum Nenhum

Adjust Second

Adiciona ou subtrai o número de segundos que você especificou na data-hora.

Nenhum Nenhum

AdjustYear Adiciona ou subtrai o número de anos que você especificou na data-hora.

Nenhum Nenhum

ConvertTo Zone

Converte a data-hora para uma zona específica.

Nenhum Nenhum

New Cria um novo objeto data-hora. NotesDateTime A nova data-hora criada

SetAnyDate

Altera a parte da data de um objeto data-hora.

Nenhum Nenhum

SetAny Time

Altera a parte da hora de um objeto data-hora

Nenhum Nenhum

SetNow Altera o valor da data-hora para a data atual e a hora corrente.

Nenhum Nenhum

Time Diffence

Dado duas data-horas, retorna a diferença em segundos das duas data-horas.

Long A diferença em segundos das data-horas

20.1 Criando um objeto data-hora

Para criar um novo objeto NotesDateTime, você pode usar tanto o método CreateDateTime da classe NotesSession ou o método New. Você fornece a string representando um valor data e hora, e os métodos retornam o novo objeto NotesDateTime representando esta data. Você pode especificar a data e hora em diferentes formatos:

• MM/DD/YYYY HH:MM:SS PM. Por exemplo, ‘ 05/29/1992 14:30:00 PM ’;

• MM/YYYY. Por exemplo, ‘ 12/2001 ‘;

• MM/DD HH:MM:SS. Por exemplo ‘ 07/27 17:04:00 ‘.

Depois de você ter um objeto NotesDateTime, você pode modificá-lo para a data e hora corrente usando o método SetNow. Você pode também usar SetAnyDate e SetAnyTime para modificar as partes de data e hora do objeto.

20.2 Convertendo uma data para e a partir de um formato LotusScript

Existem duas propriedades que deixam-no converter entre os diferentes tipos de formato de data e hora. LSLocalTime deixa-o converter uma data e hora no formato Notes para seu equivalente no formato LotusScript. Você pode também modificar a propriedade LSLocalTime para converter uma data e hora no formato LotusScript para o formato Notes. O exemplo seguinte mostra como converter uma data e hora no formato Notes para o formato LotusScript:

Dim dtNotes As New NotesDateTime(“07/27/1996 11:03 PM”)

Dim dtaLotusScript As Variant

DtaLotusScript = dtaNotes.LSLocalTime

Neste exemplo, a data e hora LotusScript é definida para representar “ 07/27/1996 11:03 PM “, sem considerar as características na zona usada pelo computador.

Você pode usar também a propriedade LSLocalTime para converter uma data e hora LotusScript para uma data e hora Notes equivalente.

O segundo método, LSGMTTime, não somente converte o formato de data e hora Notes para o formato LotusScript, como também o converte no horário de Greenwich. No exemplo anterior, se você substituir a chamada a LSLocalTime por LSGMTTime e executar o código em um computador definido para o horário Easten Standard, a data e hora LotusScript é definida como “ 07/28/1996 04:03 AM “.

Se você precisa achar a zona definida para a data e hora Notes, use a propriedade TimeZone. A propriedade retorna um número inteiro representando a zona. Quando você precisa saber se a hora salva do dia é de fato uma data e hora Notes, você pode usar a propriedade IsDST para checar. Se o computador onde você está executando o código é definido para observar a hora salva do dia, a propriedade retorna verdadeiro.

20.3 Convertendo uma data para e a partir de um texto

Se você precisa converter uma data e hora entre uma no formato Notes e um texto, você tem duas propriedades para ajudar-lhe. LocalTime e GMTTime trabalham da mesma forma a sua equivalente no LotusScript, exceto que eles traduzem valores de data e hora Notes para e a partir de uma string. Você pode também usar a propriedade ZoneTime para obter um valor data e hora mostrado na sua zona original.

20.4 Modificando um valor data e hora

Você pode modificar partes de um valor data e hora usando os métodos AdjustYear, AdjustMonth, AdjustDay, AdjustHour, AdjustMinute e AdjustSecond. Por exemplo, para calcular a data de duas semanas atrás, use o código seguinte:

Dim dtNotes As New NotesDateTime(“Today”)

Call dtNotes.AdjustDay(-14)

Os métodos são elegantes bastante para ajustar qualquer parte de um valor data e hora que é preciso atualizar. Por exemplo, se o código executa em 2 de julho, a parte do mês da data e hora é automaticamente mudada para junho. Você pode converter uma data e hora de uma zona para outra usando ConvertToZone.

20.5 Fazendo cálculos de data e hora

Use o método TimeDifference para calcular o número de segundos entre dois valores de data e hora Notes.

21 NotesDateRange

A classe NotesDateRange foi introduzida na versão 4.5 do Notes. Você usa objetos NotesDaterange para representar um espaço de tempo. Veja a tabela 3.41 para ver as propriedades da classe.

Tabela 3.41 Propriedades da classe NotesDateRange


EndDateTime O fim do período. NotesDateTime Leitura Gravação

StartDateTime

O início do período . NotesDateTime Leitura Gravação

Text O período como uma string.


A propriedade StartDateTime de um objeto NotesDateRange representa o início do período de tempo, e a propriedade EndDateTime representa o fim do período de tempo. Você pode, então, ler as datas início e fim usando a propriedade Text. Por exemplo, a propriedade Text de um objeto NotesDateRange pode ser ‘ 10/01/96 11:15:00 AM ‘ ou ‘ 10/03/96 11:15:00 AM ‘.

22 NotesName

A classe NotesName é outra classe que surgiu na versão 4.5 do Notes. Ela representa um nome de servidor ou usuário do Notes e deixa-o acessar os vários componentes de nomes hierárquicos. Por exemplo, você pode usar um objeto NotesName para extrair o componente da organização de um nome de usuário.

NOTA

Todas as propriedades da classe NotesName são somente para leitura. Logo, você não pode usar esta classe para atualizar nomes de usuário e servidor.

As propriedades da classe são mostradas na tabela 3.42 e seus métodos são mostradas na tabela 3.43.

Tabela 3.42 Propriedades da classe NotesName


Abbreviated A forma abreviada de um nome hierárquico.

String Leitura

ADMD O nome do domínio de administração parte de um nome hierárquico.

String Leitura

Canonical O nome no formato canônico. String Leitura

Common O nome comum(CN), parte de um nome hierárquico.

String Leitura

Country A região( C ), parte de um nome hierárquico.

String Leituraq

Generation A parte geração, parte de um nome hierárquico.

String Leitura

Given A parte dada de um nome. String Leitura

Initials O início de um nome. String Leitura

IsHierarquical Verdadeiro(true) se o nome é hierárquico.

Boolean Leitura

Keyword O nome no formato de keyword. String Leitura

Organization A parte organização(O) de um nome hierárquico.

String Leitura

OrgUnit1A primeira unidade(OU1)

organizacional, parte de um nome hierárquico.

String Leitura

OrgUnit2A segunda unidade(OU2)


String Leitura

OrgUnit3A terceira unidade(OU3)


String Leitura

OrgUnit4A quarta unidade(OU4) organizacional,

parte de um nome hierárquico.

String Leitura

PRMDO Domínio de gerenciamento privado,

parte de o um nome hierárquico.

String Leitura

SurnameO sobrenome, parte de um nome

hierárquico.

String Leitura

Tabela 3.43 Métodos da classe NotesName


Valor de Retorno

New Cria um novo objeto NotesName. NotesName O novo objeto NotesName

23 NotesInternational

A classe NotesInternational surgiu na versão 4.5 do Notes e lhe dar acesso a características internacionais da máquina onde o código está executando. Por exemplo, em uma máquina que executa o Windows, voc6e pode acessar as características internacionais que tem sido configurada no painel de controle.

NOTA

Se quaisquer características internacionais são mudadas, Notes reconhece as alterações imediatamente.

As propriedades da classe NotesInternational são mostradas na tabela 3.44

Tabela 3.44 Propriedades da classe NotesIternational


AMString A string que representa a hora AM( antes de meio-dia).

String Leitura

CurrencyDigits O número de dígitos depois do separador decimal.

Inteiro Leitura

Currency Symbols

O símbolo monetário. String Leitura

DateSep O caracter usado para separar o ano, mês e dia em uma data.

String Leitura

DecimalSep O caracter usado para separar as partes de um número decimal.

String Leitura

IsCurrency Space

Verdadeiro(true) se existem espaços entre símbolos monetários e a quantidade.

Boolean Leitura

IsCurrency Suffix

Verdadeiro(true) se o símbolo monetário é mostrado depois da quantidade.

Boolean Leitura

IsCurrency Zero

Verdadeiro(true) se uma fração tem um zero antes do separador decimal .

Boolean Leitura

IsDateDMY Verdadeiro(true) se o formato da data é dia/mês/ano.

Boolean Leitura

IsDateMDY Verdadeiro(true) se o formato da data é mês /dia /ano.

Boolean Leitura

IsDateYMD Verdadeiro(true) se o formato da data é ano/mês /dia.

Boolean Leitura

IsDST Verdadeiro(true) se o computador executa o código que foi definido para observar se os ajustes de hora estão tendo efeito.

Boolean Leitura

IsTime24Hours Vedadeiro(true) se o formato da hora é de 24hs.

Boolean Leitura

PMString A string que representa a hora PM( depois de meio-dia).

String Leitura

ThousandsSep O separador de milhares para números.

String Leitura

TimeSep O caracter usado para separar horas, minutos e segundos.

String Leitura

TimeZone A característica da zona. Integer Leitura

Today A string que identifica hoje na linguagem local.

String Leitura

Tomorrow A string que identifica amanhã na linguagem local.

String Leitura

Yesterday A string que identifica ontem na linguagem local.

String Leitura

24 NotesNewsLetter (Boletim Informativo)

Suponha que você tem uma coleção de documentos Notes, talvez os resultados de uma busca de texto completo de um banco de dados ou de documentos que tenham sido processados por um agente. Não seria bom se você pudesse criar um documento de sumário contendo doclinks para todos os documentos em sua coleção? Bem, use a classe NotesNewsLetter que ele pode.

A classe deixa-o criar dois tipos de documentos sumários. O primeiro tipo é baseado em todos os documentos na coleção, o segundo inclui informações de um dos documentos na coleção. Veja a tabela 3.45 para ver as propriedades da classe e a tabela 3.46 para seus métodos.

Tabela 3.45 Propriedades da classe NotesNewsLetter


DoScore Para newletters criadas usando o método FormatMsgWithDocLinks, verdadeiro(true) se o resultado relevante para cada documento pode ser incluído.


DoSubject Para newletters criadas usando o método FormatMsgWithDocLinks, verdadeiro(true) se o subject de cada documento pode ser incluído. ( Use SubjectItemName para definir Qual campo usar como subject)


SubjectItem Name

Para newletters criadas usando o método FormatMsgWithDocLinks, o nome do campo tratado como o subject ou título do documento.


Tabela 3.46 Métodos da classe NotesNewsLetter


Valor de Retorno

Format Document

Dado a posição de um documento na newsletter, cria uma imagem do documento. Então, cria um novo documento no banco de dados fornecido e armazena a imagem como o corpo do novo documento.

NotesDocument O novo documento criado

FormatMsg WithDoclinks

Dado um banco de dados, cria um documento newsletter no banco de dados.

NotesDocument O documento newsletter

New Cria um novo newsletter. NotesNewsletter O novo newsletter

24.1 Criando um NewsLetter

Você tem duas maneiras de criar um NotesNewsLetter. Você pode usar o método CreateNewsLetter da classe NotesSession ou o método New da classe NotesNewsLetter.

Em ambos você fornece uma coleção de documentos contento o conjunto de documentos que você quer incluir no newsletter.

24.2 Formatando um NewsLatter

Depois de você criar um objeto newsletter, você tem duas opções para como criar um documento de sumário a partir dele. Você pode usar o método FormatMsgWithDocLinks para criar um documento contento links para todos os documentos na coleção. Você fornece o método com o banco de dados onde será criado o novo documento.

O novo documento contém uma linha de sumário para cada documento da coleção. Por padrão, cada linha contém uma contagem(escore) de cada documento seguido por um doclink para o documento. Se você não quer incluir a contagem relevante, defina a propriedade DoScore para falso. Você pode também incluir um título para cada documento usando as propriedades DoSubject e SubjectItemName. Você define a propriedade SubjectItemName para o nome do campo que contém o texto que você quer usar como o título. Você, então, define DoSubject como verdade para incluir o título em cada linha do newsletter. Por exemplo, suponha que os documentos na coleção contém um campo chamado DocTitle que armazena o subject do documento. Se você definir SubjectName como DocTitle e DoSubject para verdadeiro(true), cada linha no newsletter consiste da contagem para o documento, um doclink para o documento seguido por um texto do campo DocTitle.

Você pode usar o método FormatDocument para criar um novo documento contento uma imagem de um documento particular da coleção. Isto é semelhante a repassar um documento, onde o novo memo de correio mostra uma imagem do documento repassado. Você fornece o método com o banco de dados onde será criado o novo documento e um número para indicar quais os documentos da coleção para incluir. O método cria o novo documento contento uma imagem do documento da coleção.

24.3 Salvando ou enviando um NewsLatter

O documento que você criou usando o método NotesNewsLetter é, para o Notes, o mesmo que qualquer documento. Você pode chamar o método de documentos Save para salvar o documento ou você pode usar o método Send para enviar o documento.

25 NotesTimer

O objeto NotesTime deixa-o definir um horário que você pode usar para disparar um evento. Você especifica um intervalo de tempo e cada tempo que o intervalo de tempo tem passado, um alarme é disparado. Suas propriedades são mostrados na tabela 3.47 e seus métodos na tabela 3.48.

Tabela 3.47 Propriedades da classe NotesTimer


Comment Um comentário para identificar o cronômetro.


Enabled Se verdadeiro(true) habilita o cronômetro.


Interval O número de segundos para esperar antes de um alarme disparar.

Integer Leitura Gravação

Tabela 3.48 Métodos da classe NotesTimer


Valor de Retorno

New Cria um novo cronômetro. NotesTimer O novo cronômetro criado

Para usar um cronômetro, execute os seguintes passos:

• Declare um objeto NotesTimer na parte declarações ou opções do script;

• Crie um objeto NotesTimer usando o método New ou CreateTimer da classe NotesSession. Você fornece um intervalo de tempo e um comentário opcional;

• Use o comando On Event Alarm para definir uma sub para chamar a cada tempo o intervalo de tempo que tem passado.

Você usa a propriedade Interval para alterar o intervalo de tempo para o cronômetro e a propriedade Comment para adicionar um comentário de identificação ao cronômetro. Você pode habilitar ou desabilitar o cronômetro usando a propriedade Enabled.

Por exemplo, para definir e usar um cronômetro para chamar uma sub a cada minuto, você primeiro declara o cronômetro nas sessões de opções e declarações como se segue:

Dim tmrMinute As NotesTimer

Então, você cria um cronômetro e define um sub para chamar quando o período de tempo do cronômetro expirar:

Set tmrMinute = New NotesTimer(60,”One minute timer”)

On Event Alarm From tmrMInute Call DoOneMinuteProcessing

Porque, por padrão, o cronômetro está habilitado, logo o sub DoOneMinuteProcessing será chamado a todo minuto.

CUIDADO

Não confie muito na precisão do tempo pois outros eventos podem atrasar o tempo de disparado do evento Alarm.