Lotus Notes

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®
– LOTUS
Exchange
– 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 - comunicase 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
%REM
A 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
Constante
s
FALSE
TRUE
NULL
NOTHING
PI
Descrição
O valor boleano é falso. Representada por 0
O valor boleano é verdadeiro. Representado por -1.
Para variáveis do tipo variante, indica que a variável não tem valor
Para variáveis que podem se referenciar a um objeto, indica que a
variável não está se referenciando a um objeto
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
Integer
Long
Single
Double
Currency
String
Variant
Número de Bytes Armazenados
1
4
4
8
8
2 por caracter
16
6. Declarando Variáveis
Sufixos
%
&
!
#
@
$
Nenhum
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
Long
Single
Double
Currence
String
Variant
I
L
S
D
Cur
Str
Var
IDocsDeleted
LFilesLength
SWeightCoefficient
DAcceleration
CurSalaryIncrease
StrDocTitle
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
Converte o valor fornecido em Currency
Converte o valor fornecido em Variant do tipo data
Converte o valor fornecido em Double
Converte o valor fornecido em Integer
Converte o valor fornecido em Long
Converte o valor fornecido em Single
Converte o valor fornecido em String
Retorna um valor Integer que representa o tipo de dado do valor fornecido
Converte o número em uma String que representa seu valor hexadecimal
Converte o número em uma String que representa seu valor octal.
Converte um número em uma String.
Retorna uma String que representa o tipo de dado do valor fornecido
Converte a String fornecida em um número do tipo Double.
Ccur
CDat
CDbl
CInt
CLng
CSng
CStr
DataType
Hex$
Oct$
Str$
TypeName
Val
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
Erase
Declara uma array estática e inicializa seus elementos
Inicializa cada elemento de uma array fixa. Para arrays
dinâmicas, deleta todos seus elementos
Dado uma variável ou expressão, Retorna verdadeiro se uma
expressão for uma array
Retorna o menor índice de uma array
Declara uma array dinâmica e aloca espaço para seus
elementos ou modifica o tamanho de uma array dinâmica
existente
Retorna o maior índice de uma array
IsArray
Lbound
ReDim
Ubound
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
Funções
Dim
Erase
ForAll
IsElement
IsList
LisTag
e
Descrição
Declara a lista
Para a lista, remove todos os seus elementos. Para elementos da
lista, remove o elemento da lista
Laço entre os elementos da lista
Dado o nome da lista e a string, retorna verdadeiro se a string é
um elemento da lista
Verifica se a variável é uma lista
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
Delete
IsObject
New
Set
With
Usado para declarar uma classe de objeto definido pelo usuário
Executa a subrotina Delete para objetos definidos pelo usuário
Retorna verdadeiro se a expressão fornecida for um objeto
Usado para criar um novo objeto definido pelo usuário
Associa um objeto a uma variável
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
GetObject
IsObject
Set
Dado o nome de uma classe de objeto OLE, Cria um objeto OLE
Dado o caminho de uma arquivo e o nome de uma classe OLE,
abre um objeto OLE a partir de um arquivo
Retorna verdadeiro se a expressão fornecida for um objeto
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
+
*
/
\
Mod
^
Número negativo
Subtrai dois números
Adiciona dois números
Multiplica dois números
Divide dois números
Divisão de inteiros
Resto de uma divisão inteira
Potência de um número
-34
7–5
5+9
7*6
16 / 5
16 \ 5
16 Mod 5
5^2
-34
2
14
42
3.5
3
1
25
Tabela 1.10 Operadores de Comparação
Operador
Descrição
Exemplo
Resultado
=
<> ><
<
Retorna verdadeiro se dois valores são iguais
Retorna verdadeiro se dois valores não são iguais
Retorna verdadeiro se um valor é menor que o
outro
Retorna verdadeiro se um valor é maior que o outro
Retorna verdadeiro se um valor é maior ou igual a
outro
Retorna verdadeiro se um valor é menor ou igual a
outro
Retorna verdadeiro se dois objetos referenciam-se
para o mesmo objeto
5=6
5 <> 6
7<9
False
True
True
7>9
8 >=8
False
True
8 <= 8
True
>
>= =>
<= =<
Is
ObjA
ObjB
Is True/False
Tabela 1.11 Operadores Lógicos
Operador
Descrição
Exemplo
Resultado
Not
And
Negação lógica
And lógico
Not B
A And B
Or
Or lógico
A Or B
Xor
Or exclusivo
A Xor B
Verdadeiro se B é falso; Falso do contrário
Verdadeiro se A e B verdadeiros; Falso do
contrário
Verdadeiro se A ou B verdadeiros; Falso do
contrário
Verdadeiro se apenas um verdadeiro; Falso
Eqv
Equivalência
lógica
Implicação lógica
Imp
A Eqv B
A Imp B
se A e B falsos ou verdadeiros
Verdadeiro se A e B são falsos ou
verdadeiros; Falso do contrário
Verdadeiro se A falso ou ambos são
verdadeiros; Falso se A verdadeiro e B falso
Tabela 1.12 Operadores de Strings
Operador
Descrição
Exemplo
Resultado
&
Concatena duas strings
“AB”+”CD”
“ABCD”
+
Concatena duas strings
“AB”+ “CD”
“ABCD”
Like
Retonra verdadeiro se uma string “ABC” Like “A*”
combina com outra string
fornecida
10
True
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 = True
Else
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:
Dim iCount As Integer
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 iCount As Integer
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 iCount As Integer
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 iCount As Integer
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 iCount As Integer
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 lblLOgError
End 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
Asc
Chr
Format
InStr
Lcase
Left
Len
Lset
Ltrim
Mid
Right
Rset
Rtrim
Space
StrCompare
Trim
Ucase
Uchr
Uni
Ustring
Descrição
Dado uma string, retorna o código de caracter da string
Dado um código de caracter, retorna o caracter correspondente ao código
Formata uma string de acordo com o tipo de formato especificado
Dado duas strings, retorna a posição do caracter(InStr) onde uma string
ocorre primeiro em outra.
Converte os caracteres de uma string em minúsculos
Dado uma string e um número n, retorna n caracteres mais a esquerda da
string
Retorna o número de caracteres de uma string
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.
Remove os espaços excedentes a esquerda de uma string
Retorna uma substring de uma string dado o início e o fim da substring
Dado uma string e um número n, retorna n caracteres mais a direita da
string
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
Remove os espaços em brancos a direita de uma string
Adiciona n espaços a um string
Compara duas strings de acordo com o método de comparação
Remove espaços a direta e a esquerda de uma string
Converte os caracteres de uma string em maiúsculos
Retorna o caracter correspondente a um número no código Unicode
Dado uma string, retorna o código de caracter Unicode, para o primeiro
caracter na string
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:
Dim strName As String
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 strName As String
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:
13
•
-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.
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
Comandos e Descrição
Funções
Date
Retorna a data e hora corrente do sistema ou altera a mesma
DateNumber Dado um ano, mês e dia do mês, retorma o valor data/hora
correspondente
DateValue
Dado uma string representando uma data, retorna um um valor data/hora
correspondente
Day
Dado um valor data/hora, retorna o dia do mês
Hour
Dado um valor data/hora, retorna a hora
IsDate
Retorna verdadeiro se uma expressão dada representa uma data
Minute
Dado um valor data/hora, renorta os minutos
Month
Dado um valor data/hora, renorta o mês
Now
Retorna a data corrente do sistema como um valor data/hora
Second
Dado um valor data/hora, renorta os segundos
Time
Retorna o hora de sistema corrente como um valor data/hora
TimeNumber Dado uma hora, minuto e segundo, retorna o valor data/hora
correspondente
Timer
Retorna o número de segundos que tenham decorrido desde meia-noite
TimeValue
Dado uma string representando uma hora, retorna o valor data/hora
correspondente
Today
O mesmo da função Date
Weekday
Dado um valor data/hora, retorna um número representando um dia da
semana
Year
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
Comandos e Descrição
Funções
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 modificado
FileLen
Dado um nome de arquivo, retorna seu tamanho em bytes
FreeFile
Retorna um número de arquivo que pode ser usado para abrí-lo
Get
Usado para ler dados de um arquivo randômico ou binário
GetFileAttr
Dado um nome de arquivo ou diretório, retorna seus atributos
Input #
Dado um número de arquivo, lê dados de um arquivo sequencial
Input
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ário
Kill
Deleta um arquivo
Line Input#
Dado um número de arquivo, retorna uma linha de um arquivo sequencial
LOC
Dado um número de arquivo, retorna a posição do arquivo de ponteiro no
arquivo
Lock
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
Open
Print #
Put
Reset
Seek
SetFileAttr
Spc
Tab
Width #
Write #
Unlock
Renomeia um arquivo ou diretório
Abre um arquivo
Imprime uma lista de variáveis de um arquivo
Escreve dados em um arquivo randômico ou binário
Fecha todos os arquivos abertos
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
Altera os atributos de sistema de arquivo de um arquivo
Insere um número específico de espaços em um comando Print ou Print(#)
Move a posição de impressão para uma coluna específica
Usado para especificar o tamanho da linha de um arquivo
Escreve uma lista de variáveis para um arquivo
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
Seqüencial
Randômico
Binário
Descrição
Um arquivo de texto
Um arquivo com registros formatados
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:
Dim iFileNumber As Integer
IFileNumber = FreeFile
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:
Dim iFileNumber As Integer
IFileNumber = FreeFile
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 strFirstName As String
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 strFirstName As String
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
Comandos e
Funções
Beep
InputBox
MessageBox
Print
Descrição
Alarma
Mostra uma caixa de diálogo onde o usuário pode entrar com um
valor
Mostra uma caixa de mensagem ao usuário
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
Comandos e
Funções
Abs
Acos
Asin
Atn
Atn2
Cos
Exp
Fix
Fraction
Int
Log
Round
Sgn
Sin
Sqr
Tan
16.1
Descrição
Retorna o valor absoluto de um número
Dado um número entre 1 e –1, retorna seu arco coseno em
radianos
Dado um número entre 1 e –1, retorna seu arco seno em radianos
Dado um número, retorna sua arco tangente em radianos
Dado as coordenadas de um ponto no plano cartesiano, retorna o
ângulo em radianos
Dado um ângulo em radianos, retorna seu coseno
Dado um número, retorna o exponencial de um número
Retorna a parte inteira de um número
Retorna a parte fracional de um número
Retorna o número inteiro que é menor ou igual ao fornecido
Retorna o logarítmo natural de um número
Arredonda um número
Retorna –1, 0 ou 1 se o número for negativo, zero ou positivo
Dado um número em radianos, retorna seu seno
Retorna a raiz quadrada de um número
Dado um ângulo em radianos, retorna sua tangente
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
Comandos e
Funções
Erl
Err
Error
On Error
Resume
Descrição
Retorna o número da linha do erro mais recente
Retorna o número do erro dependendo como ele ocorra
Retorna uma mensagem do erro dependendo como ele ocorra
Desvia a execução do código para uma função quando ocorre um erro
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á:
1
•
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
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. Palavraschave, 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
responde.
3.1
(objeto)
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:
1. Crie um novo banco de dados vazio;
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
QueryClose
Após o formulário ter sido atualizado.
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:
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 – 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 db As NotesDatabase
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
4
Evento
Trigger
Initialize
Quando o agente é iniciado.
Terminate
Quando o agente é terminado.
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;
•
4.3
Interromper – Para de executar o script.
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.
Sub Click(Source As Button)
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:
Sub Click(Source As Button)
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
Dim uiDoc As NotesUIDocument
Dim doc As NotesDocument
Set uiDoc = uiWorkSpace.CurrentDocument
Set doc = uiDoc.Document
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: frontend 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
Dim uiDoc As NotesUIDocument
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
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.
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
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
CurrentDocument
Descrição
Tipo de Dados
O documento que está sendo NotesUIDocument
mostrado
Uso
Leitura
Tabela 3.2 Método da classe NotesUIWorkspace
Método
AddDatabase
CheckAlarms
Compose
Document
DialogBox
EditDocument
EditProfile
EnableAlarms
OpenDatabase
URLOpen
Descrição
Tipo de Dados Valor
Retornados
Retornado
Adicione um novo banco de dados à área Nenhum
Nenhum
de trabalho
Checar novos alarmes no correio do banco Nenhum
Nenhum
de dados
Crie um novo UI Documente em um Banco Notes Documento O Novo UI
de Dados específico usando um formulário UI
Documento
específico e mostrando-o no modo de
edição.
Mostre uma caixa de diálogo com botões Boolean
Verdadeiro se o
“OK” e “Cancel” que contém o documento
usuário
corrente exibido usando um formulário que
seleciona “OK”
você especifica.
na caixa de
diálogo
Verdadeiro para abrir o documento Documento UI
O documento
corrente no modo de edição. Falso para
UI
abrí-lo no modo de leitura.
recentemente
aberto
Crie um novo documento de perfil ou abra Nenhum
Nenhum
uma perfil existente.
Defina com verdadeiro (True) para iniciar o Boolean
Verdadeiro se o
processo em background que checa
processo
for
alarmes.
permitido
Abra um Banco de Dados em uma visão Nenhum
Nenhum
específica e opcionalmente sublinhe um
documento específico
Abra um URL
Nenhum
Nenhum
ViewRefresh
2
Atualizar a visão de um documento
Nenhum
Nenhum
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
AutoReload
CurrentField
Document
EditMode
FieldHelp
HiddenChars
HorzScrollBar
InPreviewPane
Descrição
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.
O nome do campo aonde o cursor se
encontra
O documento back-end associado com o
documento UI corrente
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
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.
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.
Defina com Verdadeiro(True) para mostrar a
barra de rolagem horizontal. Leia para
checar se a mesma está sendo mostrada.
Verdadeiro(True) se o documento está
Tipo de dados
Boolean
Uso
Leitura
Escrita
String
Leitura
Documento
Notes
Boolean
Leitura
Boolean
Leitura
Escrita
Boolean
Leitura
Escrita
Boolean
Leitura
Escrita
Boolean
Leitura
Leitura
Escrita
IsNewDoc
PreviewDocLinks
PreviewParent
Ruler
WindowTitle
sendo
mostrado
na
janela
de
previsualização
Verdadeiro(True) se o documento nunca
tiver sido salvo
Defina com Verdadeiro(True) para mostrar a
janela de previsualização para um link. Leia
para checar se a mesma
está sendo
exibida.
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.
Defina Verdadeiro(True) para mostrar a
régua. Leia para checar se a mesma está
sendo exibida.
O título da janela para o documento que
está sendo mostrado.
Boolean
Leitura
Boolean
Leitura
Escrita
Boolean
Leitura
Escrita
Boolean
Leitura
Escrita
String
Leitura
Tabela 3.4 Métodos do NotesUIDocument
Método
Categorize
Clear
Close
CollapsAll
Sections
Copy
CreateObject
Cut
DeleteDocument
DeselectAll
ExpandAll
Sections
FieldAppendText
Descrição
Tipo de Dados Valor
Retornados
Retornado
Coloca o documento dentro de uma Nenhum
Nenhum
categoria
Somente no modo de edição, exclui texto, Nenhum
Nenhum
gráficos ou objetos que
estão
selecionados.
Fecha o documento UI atual.
Nenhum
Nenhum
Contrai todas as seções no atual Nenhum
Nenhum
documento UI aberto.
Copia
texto,
gráficos
ou
objetos Nenhum
Nenhum
selecionados para a área de transferência
Para um documento UI no modo de edição Variante
UM
“handle”
com o cursor em um campo de texto rico
para um objeto
cria um OLE ou um objeto ActiveX.
criado
recentemente
Somente no modo de edição, corta o texto, Nenhum
Nenhum
gráficos ou objeto selecionado no
documento e coloca-os na área de
transferência.
Somente no modo de leitura, marca o Nenhum
Nenhum
documento para exclusão e fecha-o
“Deseleciona” qualquer texto, gráfico ou Nenhum
Nenhum
objeto selecionados.
Expande todas as seções no documento Nenhum
Nenhum
UI aberto atualmente.
Adiciona o texto fornecido ao conteúdo de Nenhum
Nenhum
um campo (ou o campo corrente se não for
fornecido nenhum nome)
FieldClear
FieldContains
FieldGetText
FieldSetText
FindFreeTime
Dialog
Foward
GetObject
GoToBottom
GoToField
GotoNextField
GoPrevField
GotoTop
InsertText
Paste
Print
Refresh
RefreshHide
Formulas
Reload
Somente no modo de edição, limpa o Nenhum
conteúdo de um campo (ou o campo
corrente se não for fornecido nenhum
nome)
Verdadeiro(True) se um campo (ou o Boolean
campo corrente se não for fornecido
nenhum
nome)
contém
um
texto
específico.
Pega o conteúdo de um campo (ou o String
campo corrente se não for fornecido
nenhum nome). Converte o conteúdo em
uma string de texto.
Somente no modo de edição, define o Nenhum
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.
Mostra a caixa de diálogo “Tempo Livre”
Nenhum
Crie um correio Memo contendo o
documento UI aberto atualmente
Dando o nome de um OLE ou objeto
ActiveX, retorna um “Handle” para um
objeto encontrado
Somente no modo de edição, coloca o
cursor no último campo editado
Somente no modo de edição, coloca o
cursor no campo determinado
Somente no modo de edição, coloca o
cursor no próximo campo editável abaixo e
à direita da posição atual do cursor.
Somente no modo de edição, coloca o
cursor no próximo campo editável acima e
à esquerda da posição atual do cursor.
Somente no modo de edição, coloca o
cursor no primeiro campo editável
Somente no modo de edição, insera o
texto fornecido na posição onde o cursor
se encontra
Somente no modo de edição, cola o
conteúdo da área de transferência na
posição atual do cursor.
Imprime
o
documento
atual.
Opcionalmente mostra a caixa de diálogo
“File Print”
Somente no modo de edição, computa
todas as fórmulas para os campos
computados no documento
Computa todas as fórmulas ocultas em um
documento
No modo de edição, atualiza o documento
Nenhum
Verdadeiro se o
campo
comtém o texto que
você
especificou
O conteúdo do
campo
convertido em
um texto
Nenhum
Nenhum
Nenhum
Nenhum
Variante
Um
“handle”
para o objeto
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Save
SaveNewVersion
SelectAll
Send
2.1
UI com qualquer mudança que tenha sido
feita ao documento back-end associado
Somente no modo de edição, salva o
documento
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
Somente no modo de edição, seleciona o
conteúdo do campo atual. No modo de
leitura,
seleciona
o
conteúdo
do
documento inteiro
Envia o documento
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
Nenhum
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.
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Set uiDoc = uiWorkspace.CurrentDocument
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Set uiDoc = uiWorkspace.CurrentDocument
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 uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
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
CalendarDateTime
Documents
View
Descrição
Somente aplicável em visões de
calendário. A data e a hora da área
selecionada.
Uma coleção de todos os documentos na
visão atual.
A visão back-end que corresponde à
visão atual
Tipo de Dados
String
Uso
Leitura
NotesDocument
Collection
NotesView
Leitura
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
Database
Documents
Descrição
Tipo de Dados
O banco de dados back-end que NotesDatabase
corresponde ao banco de dados atual
Uma coleção de todos os documentos no NotesDocument
Uso
Somente
leitura
Somente
banco de dados.
Collection
leitura
Tabela 3.7 Métodos da classe NotesUIDatabase
Propriedade
OpenView
Descrição
Tipo de Dado de Valor
de
retorno
Retornado
Dado o nome de uma visão no banco de Nenhum
Nenhum
dados atual, abre a visão
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
AddressBooks
CommonUserName
CurrentAgent
Current Database
DocumentContext
EffectiveUserName
International
IsOnServer
LastExitStatus
LastRun
NotesVersion
Platform
SavedData
UserName
Descrição
O livro de endereços que estão disponíveis ao
script atual.
A parte do nome comum da pessoa ou
servidor rodando o script
O agente, se existir, que está rodando
atualmente
O banco de dados no qual o script está
localizado.
Para agentes que tenham sido iniciados via
Notes API e tenha criado um documento, esta
propriedade retorna o documento back-end
criado recentemente.
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.
As especificações internacionais da máquina
na qual o script está rodando.
Verdadeiro se o script está rodando em um
servidor. Falso, se o script está rodando em
uma estação de trabalho.
O código de status de saída retornado pelo
gerenciador de agentes na sua última
execução
Somente para agentes script. A data quando
o agente rodou pela última vez.
A versão do Notes na qual o script está
rodando
O tipo de sistema de operação no qual o
script está rodando
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.
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.
Tipo de Dados
Array of Notes
Databases
String
Uso
Leitura
NotesAgent
Leitura
Notes Database
Leitura
Notes Document
Leitura
String
Leitura
Leitura
NotesInternational Leitura
Boolean
Leitura
Integer
Leitura
Variante do tipo Leitura
DATA
String
Leitura
String
Leitura
Documento Notes
Leitura
String
Leitura
Tabela 3.9 Métodos da classe NotesSession
Propriedade
Descrição
CreateDate
Cria um novo objeto NotesDateRange
Close
Fecha a seção atual
Tipo de Dado Valor de Retornado
de retorno
Notes
O objeto NotesData
DataRange
Range
criado
recentemente
Nenhum
Nenhum
CreateDataTime Dada uma string representando data e NotesDataTime
O
objeto
Notes
CreateTimer
hora válidas, cria um novo objeto
NotesDateTime
Dada uma string usada para dar nome NotesLog
ao Log, cria um novo objeto NotesLog
Dado um objeto NotesDocument NotesNewsletter
Collection, cria um novo objeto
NotesNewsletter
Cria um novo objeto NotesTimer
NotesTimer
FreeTime
Search
Procura tempos livres
calendários e listas
CreateLog
CreateNews
Letter
para
GetDatabase
fazer
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
GetDbDirectory Dado o nome servidor, cria um novo
objeto NotesDbDirectory que pode ser
usado para listar os bancos de dados
num servidor
GetEnvironment Dado um nome de uma variável de
String
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
GetEnvironment Como em GetEnvironmentString mas
Value
para uma variável de ambiente
numérica
SetEnvironment Dado o nome de uma variável de
Var
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
Update
Somente para agentes script, marca
ProcessedDoc
um documento como tendo sido
processado por um agente
5.1
DataTime
criado
recentemente
O objeto Notes Log
criado recentemente
O
objeto
Notes
Newsletter
criado
recentemente
O objeto Notes Timer
criado recentemente
Array
de Uma variedade de
NotesDateRange objetos
NotesDataRange
representando vagas
(slots) disponíveis
NotesDatebase O
objeto
NotesDatabase criado
recentemente
NotesDb
Directory
O
objeto
DbDirectory
recentemente
Variant
O valor da variável do
ambiente
Variant
O valor da variável de
ambiente
Nenhum
Nenhum
Nenhum
Nenhum
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.
Notes
criado
O exemplo a seguir mostra o nome de um banco de dados no qual o script está
rodando:
Dim s As New NotesSession
Dim db As NotesDatabase
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:
Dim s As New NotesSession
Dim db As NotesDatabase
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 s As New NotesSession
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 s As New NotesSession
Dim datLastRun As Variant
DatLastRun = s.LastRun
If datLastrun = Cdat(“11/30/1999”) then
Messagebox(“Este agente não foi executado antes”)
Else
Messagebox(“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
Qualquer banco de dados Notes
Qualquer banco de dados modelo
Todos os bancos de dados
Notes disponíveis para
replicação
Todos os bancos de dados Notes que podem ser um modelo
Use Esta Constante...
DATABASE
TEMPLATE
REPLICA_CANDIDATE
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Dim DbDir As NotesDbDirectory
Dim db As NotesDatabase
Dim strDbsAvailToReplicate
Set uiDoc = uiWorkspace.CurrentDocument
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
Name
Descrição
Tipo de Dados
O nome do servidor no qual este String
diretório está localizado
Uso
Somente Leitura
Tabela 3.12 Métodos da classe NotesDbDirectory
Propriedade Descrição
GetFirst
Database
GetNext
Database
New
Tipo de Dados de Valor de retorno
retorno
Dado um tipo de banco de dados para NotesDatabase
O primeiro banco
procurar, retorna o primeiro banco de dados
de dados do tipo
daquele tipo. Você pode procurar qualquer
que
você
tipo de banco de dados, qualquer modelo, e
especificou
banco de dados que pode ser replicado, ou
qualquer banco de dados que pode ser um
modelo.
Se você já tiver usado o método First
NotesDatabase
O próximo banco
Database, retorna o próximo banco de
de dados do tipo
dados do tipo que você especificou
que
você
especificou
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
ACL
Descrição
A ACL para o banco de dados
Tipo de Dados
NotesACL
Uso
Leitura
Agents
Todos os agentes definidos no banco de Array of
dados
NotesAgents
Uma
coleção
contendo
todos
os NotesDocument
documentos de um banco de dados.
Collection
Todas as categorias às quais um banco de String
dados pertence
A data que o banco de dados foi criado
Variant of type
DATE
O nível de acesso ACL para o usuário Integer
atual
Constante
Verdadeiro(true) se múltiplas atualizações Boolean
em documentos em um servidor são
processadas
juntas
para
melhor
performance
O nome do modelo de criação para o String
banco de dados.
O nome e extensão do arquivo do banco String
de dados.
O caminho completo e nome do arquivo do String
banco de dados incluindo “drive” de leitura,
diretório, nome de arquivo e extensão.
Os formulários no banco de dados.
Array of
NotesForm
objects.
Verdadeiro(true) se o banco de dados tem Boolean
índice de texto completo.
Verdadeiro(true) se o banco de dados tem Boolean
índice de texto completo.
Verdadeiro(true) se o banco de dados Boolean
estiver aberto.
Verdadeiro(true) se o banco de dados é Boolean
Leitura
AllDocuments
Categories
Created
CurrentAccess
Level
DelayUpdates
DesignTemplate
Name
FileName
FilePath
Forms
IsFTIndexed
IsMultiDBSearch
IsOpen
IsPrivateAddress
Leitura
Leitura
Leitura
Leitura
Leitura Gravação
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Book
IsPublicAddress
Book
LastFTIndexed
LastModified
Managers
Parent
PercentUsed
ReplicaID
Server
Size
SizeQuota
TemplateName
Title
Unprocessed
Documents
Views
um Livro de Endereço Pessoal.
Verdadeiro(true) se o banco de dados é
um Livro de Endereço Público.
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.
A data que o banco de dados foi
modificado pela última vez.
Todas as pessoas, grupos e servidores
que são os administradores do banco de
dados.
O NotesSession que contém o banco de
dados.
A percentagem do banco de dados que
está em uso atualmente.
O ID de replica(16-caractere)
para o
banco de dados.
O nome do servidor no qual o banco de
dados está armazenado.
O tamanho, em bytes, do banco de dados.
O tamanho máximo, em bytes, até o qual o
banco de dados pode crescer.
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.
O título do banco de dados.
Todos
os
documentos
que
são
considerados para ser “unprocessed” pelo
script .
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.
Boolean
Leitura
Variant of type Leitura
DATE
Variant of type Leitura
DATE
Variant of type Leitura
DATE
NotesSession
Leitura
Double
Leitura
String
Leitura
String
Leitura
Double
Long
Leitura
Leitura/Gravação
String
Leitura
String
NotesDocument
Collection
Leitura/Gravação
Somente Leitura
Variant of Notes
Views
Leitura
Tabela 3.14 Métodos da classe NotesDatabase
Propriedade
Close
Compact
Create
CreateCopy
Create
Document
Descrição
Tipo de Dados Valor Retornado
Retornados
Fecha o banco de dados.
Nenhum
Nenhum
Compacta um banco de dados local. Long
O número de bytes
Perceba que você não pode usar este
recuperados na
método para compactar o banco de
compactação do banco
dados aonde o script está rodando.
Dado um servidor e um nome de Nenhum
Nenhum
arquivo, cria um novo banco de dados.
Dado um servidor e um nome de NotesDatabase
Um objeto
arquivo, cria uma cópia do banco de
NotesDatabase
dados. Dá à cópia o mesmo título e
representando a cópia
ACL do original.
criada recentemente
Cria um documento novo e vazio no NotesDocument
O documento criado
banco de dados. Note que você deve
recentemente
CreateForm
Template
CreateReplica
FTSearch
GetAgent
GetDocument
ByID
GetDocument
ByUNID
GetDocument
ByURL
GetForm
GetProfile
Document
GetURL
Header
GetView
GrantAccess
New
Open
OpenBy
ReplicaID
salvar o documento antes de de fechar
o banco; caso contrário, o documento
será perdido.
Dado um servidor, nome de arquivo e NotesDatabase
o nome de um modelo, cria um novo
banco de dados baseado no modelo.
Dado um servidor, nome de arquivo, NotesDatabase
cria uma cópia réplica do banco de
dados. Fornece a réplica com o
mesmo título e ACL do original.
Dada uma string representando uma NotesDocument
válida consulta de texto completo, o Collection
texto completo procura o banco de
dados.
Fornece um agente dado seu nome.
NotesAgent
Dado o NotesID de um documento, NotesDocument
encontra o documento.
Similar ao anterior porém usa o UNID. NotesDocument
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.
Pega um formulário dado o seu nome
ou alias.
Pega um documento Profile do banco
de dados.
Para o banco de dados Web
Navigator, dado um URL e string de
cabeçalho, retorna a informação do
cabeçalho URL requerida.
Dado o nome ou alias de uma visão ou
pasta, retorna a visão ou pasta.
Muda o ACL para o banco de dados
para dar à pessoa, grupo ou servidor
um nível de acesso específico.
Cria um novo objeto banco de dados
Notes. Note que este método não cria
um novo banco de dados no disco.
Dado um servidor e um nome de
arquivo, abre um banco de dados
existente.
Um objeto do banco de
dados Notes
representando o banco
criado recentemente
Um objeto do banco de
dados Notes representando o banco criado
recente-mente
Uma coleção de
documentos
atendendo aos
critérios da consulta,
classificada de forma
que os documentos
mais relevantes estão
em primeiro lugar
O agente
O documento
O documento
NotesDocument
O documento
correspondente à URL
NotesForm
O formulário
NotesDocument
O documento profile
String
A informação de
cabeçalho
NotesView
A visão ou pasta
requisitado
Nenhum
Nenhum
Banco de dados O objeto criado
Notes
recentemente
Boolean
Similar ao Open, mas usa o nome do Open
servidor fornecido e replica ID para
Verdadeiro se o banco
de dados foi
encontrado e aberto
com sucesso
Verdadeiro se o banco
de dados foi
encontrar o banco de dados
OpenIf
Modified
OpenMail
OpenURLDB
Dado um servidor, nome de arquivo e Boolean
data abre um banco de dados
existente, sob a condição que tenha
sido modificado desde a data que você
especificou.
Abre o correio do banco de dados do Nenhum
usuário atual.
Abre o Navegador Web default do Boolean
banco de dados.
OpenWithFail
Over
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.
QueryAccess Dado o nome de uma pessoa, grupo
ou servidor, devolve seus níveis de
acesso ao banco de dados.
Remove
Exclui o banco de dados.
Replicate
Dado o nome de um servidor, replica o
banco de dados com sua réplica
naquele servidor.
RevokeAccess Remove uma pessoa, grupo ou
servidor do ACL para o banco de
dados.
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.
Boolean
Unprocessed
FTSearch
NotesDocument
Collection
Unprocessed
Search
UpdateFT
Index
7.1
Somente para agentes script, o
mesmo que FTSearch, exceto que só
são procurados aqueles documentos
que
o
agente
considera
não
processados.
Somente para agentes script, o
mesmo que Search, exceto que só são
procurados aqueles documentos que o
agente considera não processados.
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.
Criando um Banco de Dados
encontrado e aberto
com sucesso
Verdadeiro se o banco
de dados tiver sido
encontrado e aberto
com su-cesso
Nenhum
Verdadeiro se o banco
de dados tiver sido
encontrado e aberto
com sucesso
Verdadeiro se o banco
de dados foi
encontrado e aberto
com sucesso
Integer Constant
O nível de acesso
Nenhum
Boolean
Nenhum
Verdadeiro se o banco
de dados foi replicado
com sucesso
Nenhum
Nenhum
NotesDocument
Collection
Todos os documentos
que com binam com a
fórmula e têm sido
modificados desde a
data separada
Os documentos
NotesDocument
Collection
Os documentos
Nenhum
Nenhum
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 s As New NotesSession
Dim db As NotesDatabase
Dim dbTemplate As New NotesDatabase(“Sapphire”, “report.ntf”)
Dim dbReplica As NotesDatabase
Set db = s.CurrentDatabase
‘ 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.
Sub Click(Source As Button)
Dim s As New NotesSession
Set db = s.CurrentDatabase
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:
Sub Click(Source As Button)
Dim s As New NotesSession
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:
Sub Click(Source As Button)
Dim s As New NotesSession
Dim db As NotesDatabase
Dim iAccessLevel AS Integer
Set db = s.CurrentDatabase
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 Else
Print “ 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 s As New NotesSession
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
http://www.lotus.com”, True)
=
dbWebNavigator.GetDocumentByURL(“
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.
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
Aliases
AutoUpdate
Columns
Created
IsCalendar
IsDefaultView
IsFolder
LastModified
Name
Parent
ProtectReaders
Readers
UniversalID
Descrição
O aliases de uma visão.
Deixe-a como true se a visão front-end é
atualizada automaticamente quando da
atualização da visão back-end.
Todas as colunas na visão ou pasta.
Tipo de Dado
Array of string
Boolean
Array of Notes
ViewColumns
A data e hora em que a visão ou pasta foi Variant of date
criada.
type
Verdadeiro se a visão é um visão de
Boolean
calendário.
Verdadeiro se a visão é a padrão
Boolean
Verdadeiro se o objeto é uma pasta
Boolean
A data e hora quando a visão ou pasta foi Variant of type
modificada pela última vez.
date
Pode ser seu nome, alias ou ambos.
String
O banco que contém a visão ou pasta.
NotesDatabase
Defina como verdadeiro para proteger o
Boolean
item $Readers durante a replicação.
O nome das pessoas, grupos e
Array of string
servidores que podem ler a visão,
Um ID de 32 caracteres que identifica a
String
visão ou pasta em todas as réplicas de
um banco de dados particular.
Tabela 3.17 Métodos da classe NotesView
Uso
Leitura
Leitura
Gravação
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Leitura
Gravação
Leitura
Gravação
Leitura
Método
Descrição
Clear
Se a visão foi filtrada usando uma
busca de texto completo, limpa a
visão e todos os documentos são
mostrados.
Dado uma string representado uma
Integer
consulta de texto completo, encontra
o banco de dados e mostra as visões
que satisfazem a consulta.
Dado uma chave, acha todos os
NotesDocument
documetnos na visão que satisfazem Collection
a chave.
FTSearch
GetAllDocuments
ByKeys
GetChild
Dado um documento na visão, acha
a primeira reposta do documento.
Tipo de Dados
Retornados
Nenhum
NotesDocument
NotesDocument
O documento
NotesDocument
O documento pai
NotesDocument
O documento
NotesDocument
O documento
Nenhum
Nenhum
Nenhum
Nenhum
NotesDocument
NotesDocument
GetLastDocument
Obtém o último documento da visão.
NotesDocument
Obtém o próximo documento da
visão a partir do documento atual.
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.
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.
Remove
Exclui a visão de um banco de
dados.
NotesDocument
8.1
Nenhum
O número de
documentos que
satisfazem a
consulta
Uma coleção de
documentos que
satisfazem a
consulta
A primeira
resposta do
documento
O primeiro
documento com a
chave
O primeiro
documento da
visão
O último
documento da
visão
O próximo
documento
O documento
GetDocumentBy Key Dado uma chave, acha o primeiro
documento que possui a chave
fornecida.
GetFirstDocument
Obtém o primeiro documento da
visão.
GetNextDocument
Valor Retornado
NotesDocument
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
IsCategory
IsHidden
IsResponse
Representação textual de uma fórmula.
Verdadeiro se a coluna está categorizada.
Verdadeiro se a coluna está oculta.
Verdadeiro se a coluna é somente
resposta.
Verdadeiro se a coluna está ordenada.
Se a coluna exibe o valor de um campo, o
nome do campo.
A posição da coluna na visão.
O título da coluna se ela tiver.
String
Boolean
Boolean
Boolean
Leitura
Leitura
Leitura
Leitura
Boolean
String
Leitura
Leitura
Integer
String
Leitura
Leitura
IsSorted
ItemName
Position
Title
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
Propriedade
Descrição
Tipo de Dado
Usado
Authors
O nome das pessoas que tem salvo
os documentos.
O valor de uma coluna para um
documento
A data de criação do documento.
Todos os objetos ActiveX e OLE no
documento.
Array of strings
Leitura
Array of variants
Leitura
Variant do type data
Array of
NotesEmbedded
Objects
String or Array of
Strings
Boolean
Leitura
Leitura
ColumnValues
Created
Embedded
Objects
EncryptionKeys
A chave usada para encriptar
documentos.
EncryptOnSend Verdadeiro(true) se o documento é
para ser encriptado quando enviado.
FTSearchScore A contagem de documentos
encontrados a partir de uma
pesquisa.
HasEmbedded Verdadeiro(true) se o documento
contem pelo menos um objeto
lincado ou arquivo anexado.
IsNewNote
Verdadeiro(true) se o documento
nunca foi salvo.
IsProfile
Verdadeiro(true) se o documento é
do tipo profile(perfil).
IsResponse
Verdadeiro(true) se o documento é
do tipo resposta.
IsSigned
Verdadeiro(true) se o documento tem
pelo menos uma assinatura.
IsUIdocOpen
Verdadeiro(true) se o documento foi
acessado por um NotesUIDocument.
IsUnread
Verdadeiro(true) se o documento é
marcado como não leitura para o
usuário corrente.
Items
Todos os itens armazenados em um
documento.
Key
A chave de um documento de perfil.
LastAccessed
A última data em que o documento
foi lido ou alterado.
LastModified
A última data em que o documento
foi modificado.
NameOfProfile O nome do documento de profile.
NoteID
Um ID de 8 caracteres que identifica
o documento em um banco de
dados.
ParentDataBase O banco que contem o documento.
ParentDocumen Para documentos respostas, um ID
t UNID
de 32 caracteres que identifica o pai
de um documento.
ParentView
A visão de onde o documento foi
recuperado ou acessado.
Responses
As respostas imediatas para um
Integer
Leitura
Gravação
Leitura
Gravação
Leitura
Boolean
Leitura
Boolean
Leitura
Boolean
Leitura
Boolean
Leitura
Boolean
Leitura
Boolean
Leitura
Boolean
Leitura
Array of NotesItems Leitura
String
Variant of type
DATE
Variant of type
DATE
String
String
Leitura
Leitura
NotesDatabase
String
Leitura
Leitura
NotesView
Leitura
Notes Document
Leitura
Leitura
Leitura
Leitura
SaveMessage
OnSend
SendByAgent
Signer
SignOnSend
Size
UniversalID
Verifier
documento.
Verdadeiro(true) se o documento é
para ser salvo quando enviado.
Verdadeiro(true) se o documento foi
enviado através de script.
Falso(false) se o documento foi
enviado por uma pessoa.
Se o documento foi assinado, o
nome da pessoa que assinou o
documento.
Verdadeiro(true) se o documento é
para ser assinado quando enviado.
O tamanho do documento em bytes
incluindo arquivos anexados.
Um ID de 32 caracteres que identifica
documentos em todas as réplicas de
um banco de dados.
O nome da certificado que verifica a
assinatura de um documento
assinado.
Collection
Boolean
Leitura
Boolean
Leitura
String
Leitura
Boolean
Long
Leitura
Gravação
Leitura
String
Leitura
String
Leitura
Tabela 3.20 Métodos da classe NotesDocument
Método
Descrição
Append
ItemValue
Cria um novo item no documento e
NotesItem
define seu valor ou adiciona um valor a
um item existente.
Executa todos os valores padrões,
Boolean
transações de entrada e fórmulas de
validação para os documentos usados.
Compute
With Form
CopyAll
Item
CopyItem
CopyTo
Database
Create
Reply
Message
Create
RichText
Item
Encrypt
Get
Attachment
GetFirst
Item
GetItem
Dado de retorno
Valor
de
retorno
O novo item
Verdadeiro se
todas as
fórmulas
executadas
tiveram
sucesso
Nenhum
Copia todos os itens de um
documento para o outro.
Copia um item no documento corrente.
Copia um documento para um banco
de dados.
Cria um novo documento como
resposta do documento corrente.
Nenhum
Cria um campo de texto rico no
documento.
NotesRichText
Item
O novo item
O novo
documento
O novo
documento
resposta
O novo campo
de texto rico
Criptografa o documento.
Obtém o nome do arquivo anexado ao
documento.
Obtém o primeiro item com o nome
fornecido no documento.
Obtém o valor do item do documento
Nenhum
Notes Embedded
Object
NotesItem
Nenhum
O arquivo
atachado
O item
NotesItem
NotesDocument
NotesDocument
String para campo O valor
Value
cujo nome foi fornecido.
GetNext
Item
HasItem
Obtém o próximo item cujo nome seja
o mesmo do fornecido.
Verdadeiro(true) se o documento tem
um item com o nome fornecido.
Make
Torna o documento corrente uma
Response
resposta do fornecido.
PutInFolder Põe o documento em uma pasta
fornecida. Cria a pasta se não existir.
Remove
Exclui o documento.
Remove
FromFolder
Remove
Item
RenderTo
RTItem
Replace
ItemValue
Save
Send
Sign
10.1
rico. Array of
strings para
campo texto ou
lista. Array of
double para
números, lista de
números e
data/hora
NotesItem
Boolean
O item
Nenhum
Verdadeiro se
o item existe
Nenhum
Nenhum
Nenhum
Boolean
Remove o documento de uma pasta
especificada.
Exclui todos os items com um nome
específico de um documento.
Cria uma imagem de um documento e
armazena esta imagem em um campo
rico.
Substitui todos os itens especificados
e atribui novos valores.
Salva todas as mudanças feitas em
um documento.
Nenhum
Verdadeiro se
o documento
foi excluído
Nenhum
Nenhum
Nenhum
Boolean
Verdadeiro se
a figura foi
criada
O novo item
Envia um documento para os
recipientes especificados.
Adiciona a assinatura do usuário
corrente ao documento.
Nenhum
Verdadeiro se
documento foi
salvo
Nenhum
Nenhum
Nenhum
NotesItem
Boolean
Criando um documento
Você cria um novo documento usando tanto o método CreateDocument
NotesDatabase quanto o método New.
10.2
da classe
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:
Sub Click(Source As Button)
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Dim doc As NotesDocument
Dim varQuantity As Variant
Set uiDoc = uiWorkspace.CurrentDocument
Set doc = uiDoc.Document
VarQuantity = doc.GetItemValue(“Quantity”);
End Sub
O exemplo seguinte faz o mesmo que o anterior mas usa sintaxe de classe
estendida:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Dim doc As NotesDocument
Dim varQuantity As Variant
Set uiDoc = uiWorkspace.CurrentDocument
Set doc = uiDoc.Document
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:
Sub Click(Source As Button)
Dim uiWorkspace As New NotesUIWorkspace
Dim uiDoc As NotesUIDocument
Dim doc As NotesDocument
Dim itmTitle As NotesItem
Dim itmPlace As NotesItem
Set uiDoc = uiWorkspace.CurrentDocument
Set doc = uiDoc.Document
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
Aliases
O aliases de um formulário.
Fields
Os nomes dos campos no formulário.
FormUsers
Os nomes dos usuários que podem usar o
formulário (O conteúdo do campo
$FormUsers).
Verdade se o formulário é um subformulário. Boolean
O nome do formulário.
String
IsSubForm
Name
Tipo de
Dado
Array of
strings
Array of
string
Array of
strings
Usado
Leitura
Leitura
Leitura/
Gravação
Leitura
Leitura
Protect
Torne-o verdadeiro(true) para proteger o
Readers
item $Readers durante a replicação.
ProtectUsers Torne-o verdadeiro(true) para proteger o
item $FormUsers durante a replicação.
Readers
O nome dos usuários que podem ler o
formulário(O conteúdo do campo $Readers).
Boolean
Boolean
Array of
strings
Leitura/
Gravação
Leitura/
Gravação
Leitura/
Gravação
Tabela 3.22 Métodos da classe NotesForm
Método
Descrição
Remove
Exclui um formulário de um banco de Nenhum
dados.
12
Tipo de Dado Usado
Nenhum
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
Propriedade
Descrição
Tipo de Dado
Usado
DateTime
Value
IsAuthors
IsEncrypted
NotesDate Time
Boolean
Boolean
Leitura/
Gravação
Leitura
Leitura
Boolean
Boolean
Leitura
Leitura
Boolean
Boolean
Leitura
Leitura
IsSummary
LastModified
Somente para itens data/hora. Um objeto
NotesDateTime representando o item.
Verdadeiro(true) se o item é um autor.
Verdadeiro(true) se o item está
encriptado.
Verdadeiro(true) se o item é um nome.
Verdadeiro(true) se o item pode ser
alterado por um usuário que possua pelo
menos acesso editor.
Verdadeiro(true) se o item é um leitor.
Verdadeiro(true) se o item contêm uma
assinatura eletrônica.
Verdadeiro(true) se o item é um sumário.
A data de última modificação do item.
Leitura
Leitura
Name
O nome do item.
Boolean
Variant of type
date
String
IsNames
IsProtected
IsReaders
IsSigned
Leitura
Parent
SaveToDisk
Text
Type
ValueLength
Values
O documento que contêm o item.
Verdadeiro(true) se o item deveria ser
salvo no disco quando o documento que
o contêm é salvo.
A representação textual de um item. Lista
de itens são separados por ponto-evírgula.
O tipo do item.
O tamanho, em bytes, do item .
Os valores armazenados no item.
Notes Document
Boolean
Leitura
Leitura
String
Leitura
Integer constant
Integer
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
Leitura
Leitura/
Gravação
Tabela 3.24 Métodos da classe NotesItem
Método
Descrição
Tipo de Dado Valor
de
de Retorno
Retorno
Abstract
Abrevia o texto do item.
String
Texto
abreviad
o
AppendTo
Para um item de lista de texto, adiciona Nenhum
TextList
um outro valor no final da lista.
Nenhum
Contains
Para itens contento listas, verifica se o Boolean
valor fornecido por você está na
lista. Pode ser usado em listas do
com números, textos e datas.
Verdadeiro
se
o
valor
está na
lista
CopyItem
ToDocu
ment
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
Propriedade
Descrição
Embedded
Objects
Todos os objetos OLE, ActiveX e Array
arquivos do item de texto rico.
Tabela 3.26 Métodos da classe NotesRichTextItem
Tipo de Dado
Usado
of Leitura
NotesEmb
edded
Objects
Método
Descrição
Tipo de Dado
Usado
AddNewLine Adiciona uma ou mais linhas ao Nenhum
item de texto rico.
Nenhum
AddTab
Adiciona um ou mais caracteres de Nenhum
tabulação ao item de texto rico.
Nenhum
AppendDoc
Link
Dado um banco de dados, uma Nenhum
visão ou documento, cria um
link para o objeto e adiciona-o
ao item de texto rico.
Nenhum
AppendRT
File
Dado um arquivo no formato de Nenhum
texto
rico,
adiciona
seu
conteúdo ao item de texto rico.
Nenhum
AppendRT
Item
Adiciona um item de texto rico a Nenhum
outro.
Nenhum
AppendText
Adiciona o texto fornecido ao item Nenhum
de texto rico.
Nenhum
EmbedObjec Dado o nome de um arquivo ou NotesEmbedded
t
aplicação, cria o objeto, um link
Object
ou um arquivo anexado e
armazena-o no campo de texto
rico.
O
Get
Object
Embedd
ed
Object
Dado o nome de um objeto, link ou NotesEmbedded
arquivo anexado a um item de
Object
texto
rico,
retorna
o
NotesEmbeddedObject
correspondente.
novo
objeto
criado
GetFormatte Retorna o conteúdo do item de texto String
dText
rico como uma string.
O texto do
item de
texto
rico
New
O novo item
de texto
rico
criado
Cria um item richtext.
13.1
NotesRichText
Item
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 doc As NotesDocument
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
Propriedade
Descrição
Tipo de Dado
Class
O nome da aplicação que criou String
objeto.
Leitura
FileSize
O tamanho, em bytes, do objeto.
Leitura
Name
O nome usado para referenciar o String
objeto.
Leitura
Object
O OLE handle para o objeto.
Leitura
Parent
O item de texto rico que contêm o NotesRichTextItem
objeto.
Leitura
Source
Para arquivos anexados, o nome do String
arquivo. Para outros tipos de
objetos, um nome interno
usado pelo Notes.
Leitura
Type
Mostra o tipo do objeto.
Leitura
Verbs
Para objetos OLE2, os verbos Array of string
suportados pelo objetivo
Long
Variant
IntegerConstant
Tabela 3.28 Métodos da classe NotesEmbeddedObject
Usado
Leitura
Método
Descrição
Activate
Somente para objetos embutidos ou Variant
linkados, carrega o objeto e
ativa sua aplicação de servidor
OLE.
-
DoVerb
Somente para objetos embutidos, Nenhum
executa o verbo fornecido.
Nenhum
ExtractFile
Somente para arquivos anexados, Nenhum
copia o arquivo anexado para o
nome de arquivo fornecido.
Nenhum
Remove
Exclui o objeto embutido, linkado Nenhum
ou o arquivo anexado.
Nenhum
14.1
Tipo de Dado de Valor
de
Retorno
Retorno
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
Propriedade
Descrição
Tipo de Dado
Count
O
número de
coleção.
IsSorted
Se
a coleção está ordenada. Boolean
Somente
as
coleções
produzidas por uma consulta de
texto
completo
serão
ordenadas.
Parent
O banco de dados que contém a NotesDatabase
coleção.
Leitura
Query
A consulta usada para selecionar a String
coleção que foi produzida por
uma busca.
Leitura
documentos
na Long
Usado
Leitura
Leitura
Tabela 3.30 Métodos da classe NotesDocumentCollection
Método
Descrição
GetFirst
Obtém o primeiro documento da NotesDocument
coleção.
Document
GetLast
Obtém o último
Docume
coleção.
nt
Tipo de Dado de
Retorno
O primeiro
docum
ento
da NotesDocument
O
último
docum
ento
GetNext
Obtém o próximo documento da NotesDocument
Docume
coleção em relação ao atual.
nt
O
próximo
docum
ento
GetNth
Obtém um documento na posição NotesDocument
do índice dado.
O
Obtém o documento anterior ao Notes Document
atual da coleção.
O
Document
GetPrev
Document
documento
Valor
de
Retorno
docum
ento
docum
ento
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:
Sub Click(Source As Button)
Dim s As New NotesSession
Dim db As NotesDatabase
Dim coll As NotesDocumentCollection
Set db = s.CurrentDatabase
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 s As New NotesSession
Dim db As NotesDatabase
Dim coll As NotesDocumentCollection
Dim dtLastWeek As New NotesDateTime( “Today”)
Set db = s.CurrentDatabase
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
Propriedade
Descrição
Tipo de Dado
Usado
Comment
O comentário associado ao agente.
String
Leitura
Common
Owner
O nome comum da pessoa que por String
último editou o agente.
Leitura
IsEnabled
Verdadeiro(true)
abilitado.
está Boolean
Leitura
IsPublic
Verdadeiro(true) se o agente está Boolean
disponível para todos os bancos de
dados dos usuários.
Leitura
LasRun
A última data na qual o agente foi Variant of type Leitura
executado.
DATE
Name
O nome do agente.
String
Leitura
Owner
O nome completo da pessoa que por String
último editou o agente.
Leitura
Parent
O banco de dados onde o agente está NotesDatabase Leitura
armazenado.
Query
O
se
o
agente
texto da consulta usado para String
selecionar os documentos onde o
agente executa.
Leitura
ServerName Para agentes no servidor, o nome String
completo do servidor onde o agente
executa. Para agentes locais, o
nome completo do usuário corrente.
Leitura
Tabela 3.32 Métodos da classe NotesAgent
Método
Descrição
Tipo de Dado de
Retorno
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
Propriedade
Descrição
Tipo de Dado
Usado
Parent
O banco de dados que contém a NotesDatabase
ACL.
Leitura
Roles
Todas as regras definidas na ACL.
Leitura
Array of strings
Tabela 3.34 Métodos da classe NotesACL
Método
AddRole
Descrição
Tipo de Dado
de Retorno
Dado o nome da regra, adiciona a Nenhum
regra a ACL.
Valor de Retorno
Nenhum
Create ACL Dado uma pessoa, grupo ou nome NotesACLEntry
Entry
de servidor e um nível de
acesso, cria uma nova entrada
na ACL.
A nova entrada
na ACL
DeleteRole
Dado o nome da regra, exclui a Nenhum
função da ACL.
Nenhum
GetEntry
Dado uma pessoa, grupo, ou nome NotesACL
de servidor, acha a entrada
correspondente na ACL.
A
entrada na
ACL
para
uma
pessoa,
grupo
ou
servidor
NotesACLEntry
A
primeira
entrada na
ACL
GetNextEntr Dada qualquer entrada na ACL, NotesACLEntry
y
acha a próxima.
A
próxima
entrada na
ACL
RenameRole Dado o nome da regra, acha a None
regra e a renomea.
None
Save
None
GetFirstEntr Acha a primeira entrada na ACL
y
Salva alterações feitas na ACL
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
Propriedade
Descrição
Tipo de Dado
Usado
CanCreate
Documents
Verdadeiro(true) se a entrada da ACL Boolean
pode criar documentos no banco
de dados.
Leitura
Gravaç
ão
CanCreate
Personal
Agent
Verdadeiro(true) se a entrada da ACL Boolean
pode criar agentes pessoais no
banco de dados.
Leitura
Gravação
CanCreate
Personal
Folder
Verdadeiro(true) se a entrada da ACL Boolean
pode criar pastas pessoais no
banco de dados.
Leitura
Gravação
CanDelete
Verdadeiro(true) se a entrada da ACL Boolean
Documen
pode excluir documentos
do
ts
banco de dados.
Leitura
Gravação
Level
O nível de acesso para esta entrada Integer Constant Leitura
da ACL.
Gravação
Name
O nome associado a entrada da ACL.
String
Parent
A ACL que contém a entrada.
NotesACL
Roles
As regras que são definidas para esta Array of strings
entrada da ACL.
Leitura
Gravação
Leitura
Leitura
Tabela 3.36 Métodos da classe NotesACLEntry
Método
Tipo de Dado
de Retorno
DisableRol Dado o nome da regra, remove a Nenhum
e
regra da entrada na ACL.
Valor de Retorno
EnableRole Dado o nome da regra, adiciona a Nenhum
regra a entrada da ACL.
Nenhum
IsRole
Dado o nome da função, checar se a Boolean
Enable
entrada da ACL tem a regra
d
abilitada.
Verdadeiro se a
função está
abilitada
New
Cria uma nova entrada na ACL.
A nova entrada
criada
Remove
Exclui a entrada da ACL fornecida a Nenhum
partir da ACL.
18.1
Descrição
NotesACLEntry
Nenhum
Nenhum
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:
Sub Click(Source As Button)
Dim s As New NotesSession
Dim db As NotesDatabase
Dim acl As NotesACL
Set db = s.CurrentDatabase
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
Propriedade
Descrição
LogActions
Verdadeiro(true) se as ações devem Boolean
ser registradas.
Leitura
LogErrors
Verdadeiro(true) se os erros devem Boolean
ser armazenados.
Leitura
NumActions
O número de ações que têm sido Integer
registradas.
Leitura
NumErros
O
Leitura
número de
registrados.
Tipo de Dado
erros
que
foram Integer
Usado
OverWriteFile Se o log está sendo gravado em um Boolean
arquivo. Diz se um arquivo de log
deve ser sobrescrevido com este
log ou adicionado este log a ele.
Leitura
Gravaç
ão
ProgramNam
e
Leitura
Gravaç
ão
O nome que identifica o script e é String
usado
para
identificar
as
entradas do log.
Tabela 3.38 Métodos da classe NotesLog
Método
Descrição
Close
Fecha um log.
LogAction
Escreve uma ação de mensagem no Nenhum
log.
Nenhum
LogError
Escreve uma mensagem de erro no Nenhum
log.
Nenhum
LogEvent
Gera um evento Notes.
Nenhum
Nenhum
New
Cria um novo log.
NotesLog
O
Nenhum
Nenhum
OpenFile
Log
Dado um nome de um arquivo, abre o Nenhum
arquivo e escreve qualquer ação
subsequente ou mensagens de
erro no arquivo.
Nenhum
OpenMail
Log
Cria um novo mail memo endereçado Nenhum
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
OpenNotes Dado um nome de servidor e arquivo, Nenhum
Log
abre o banco de dados de log
específico. Escreve qualquer
ação subsequente ou mensagens
de erro ao banco de dados.
Nenhum
OpenAgent Abre um log de um agente.
Log
19.1
Tipo de Dado
de Retorno
Nenhum
Valor de Retorno
Nenhum
novo
criado
log
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
Propriedade
Descrição
Tipo de Dado
GMTTime
A data-hora convertida para o horário String
de Greenwich.
Leitura
IsDST
Verdadeiro(true) se o computador Boolean
executa o código que foi definido
para observar se os ajustes de
hora estão tendo efeito.
Leitura
LocalTime
A data-hora da zona local.
Leitura
Gravaç
ão
LSGMTime
A data-hora
convertida para o Variant of type
horário de Greenwich.
DATE
Leitura
LSLocalTime
A data-hora da zona local.
Leitura
TimeZone
A zona corrente.
ZoneTime
A
String
Variant of type
DATE
Integer
data-hora ajustada para as String
propriedades TimeZone e IsDST
e retornada como uma string.
Tabela 3.40 Métodos da classe NotesDateTime
Usado
Leitura
Leitura
Método
Descrição
Tipo de Dado
de Retorno
AdjustDay
Adiciona ou subtrai o número de dias Nenhum
que você especificou na data-hora.
Nenhum
AdjustHour Adiciona ou subtrai o número de horas Nenhum
que você especificou na data-hora.
Nenhum
Adjust
Adiciona ou subtrai o número de Nenhum
Minute
minutos que você especificou na
data-hora.
Nenhum
Adjust
Month
Adiciona ou subtrai o número de Nenhum
meses que você especificou na
data-hora.
Nenhum
Adjust
Secon
d
Adiciona ou subtrai o número de Nenhum
segundos que você especificou na
data-hora.
Nenhum
AdjustYear Adiciona ou subtrai o número de anos Nenhum
que você especificou na data-hora.
Nenhum
ConvertTo
Zone
Converte a data-hora para uma zona Nenhum
específica.
Nenhum
New
Cria um novo objeto data-hora.
A nova datahora
criada
SetAnyDat
e
Altera a parte da data de um objeto Nenhum
data-hora.
Nenhum
SetAny
Time
Altera a parte da hora de um objeto Nenhum
data-hora
Nenhum
SetNow
Altera o valor da data-hora para a data Nenhum
atual e a hora corrente.
Nenhum
NotesDateTime
Time
Dado duas data-horas, retorna a Long
Diffenc
diferença em segundos das duas
e
data-horas.
20.1
Valor
de
Retorno
A
diferença
em
segundo
s
das
datahoras
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
Propriedade
Descrição
Tipo de Dado
Usado
EndDateTime
O fim do período.
NotesDateTime
Leitura Gravação
StartDateTim
e
O início do período .
NotesDateTime
Leitura Gravação
Text
O
período
string.
como
uma String
Leitura Gravação
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
Propriedade
Descrição
Tipo de Dado
Abbreviated
A
nome String
Leitura
ADMD
O nome do domínio de administração String
parte de um nome hierárquico.
Leitura
Canonical
O nome no formato canônico.
String
Leitura
Common
O nome comum(CN), parte de um String
nome hierárquico.
Leitura
Country
A região( C ), parte de um nome String
hierárquico.
Leituraq
Generation
A parte geração, parte de um nome String
hierárquico.
Leitura
Given
A parte dada de um nome.
String
Leitura
Initials
O início de um nome.
String
Leitura
é Boolean
Leitura
forma abreviada
hierárquico.
IsHierarquical Verdadeiro(true)
hierárquico.
se
de
o
um
nome
Usado
Keyword
O nome no formato de keyword.
String
Leitura
Organization
A parte organização(O) de um nome String
hierárquico.
Leitura
String
Leitura
String
Leitura
String
Leitura
String
Leitura
String
Leitura
OrgUnit1
OrgUnit2
OrgUnit3
OrgUnit4
PRMD
A
primeira
unidade(OU1)
organizacional, parte de um nome
hierárquico.
A
segunda
unidade(OU2)
organizacional, parte de um nome
hierárquico.
A
terceira
unidade(OU3)
organizacional, parte de um nome
hierárquico.
A quarta unidade(OU4) organizacional,
parte de um nome hierárquico.
O Domínio de gerenciamento privado,
parte de o um nome hierárquico.
Surname
O sobrenome, parte de um nome
hierárquico.
String
Leitura
Tabela 3.43 Métodos da classe NotesName
Método
Descrição
Tipo de Dado
de Retorno
Valor
de
Retorno
New
Cria um novo objeto NotesName.
NotesName
O
23
novo
objeto
NotesNa
me
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
Propriedade
Descrição
Tipo de Dado
AMString
A string que representa a hora String
AM( antes de meio-dia).
Leitura
CurrencyDigits O número de dígitos depois do Inteiro
separador decimal.
Leitura
Currency
Symbols
O símbolo monetário.
String
Leitura
DateSep
O caracter usado para separar o ano, String
mês e dia em uma data.
Leitura
DecimalSep
O caracter usado para separar as String
partes de um número decimal.
Leitura
IsCurrency
Space
Verdadeiro(true) se existem espaços Boolean
entre símbolos monetários e a
quantidade.
Leitura
IsCurrency
Suffix
Verdadeiro(true)
se
o
símbolo Boolean
monetário é mostrado depois da
quantidade.
Leitura
IsCurrency
Zero
Verdadeiro(true) se uma fração tem Boolean
um zero antes do separador
decimal .
Leitura
IsDateDMY
Verdadeiro(true) se o formato da data Boolean
é dia/mês/ano.
Leitura
IsDateMDY
Verdadeiro(true) se o formato da data Boolean
é
mês /dia /ano.
Leitura
IsDateYMD
Verdadeiro(true) se o formato da data Boolean
é
ano/mês /dia.
Leitura
IsDST
Verdadeiro(true) se o computador Boolean
executa o código que foi definido
para observar se os ajustes de
hora estão tendo efeito.
Leitura
IsTime24Hours Vedadeiro(true) se o formato da hora Boolean
é de 24hs.
Leitura
PMString
Leitura
A string que representa a hora String
PM( depois de meio-dia).
ThousandsSep O
separador
números.
de
milhares
para String
Usado
Leitura
TimeSep
O caracter usado para separar horas, String
minutos e segundos.
Leitura
TimeZone
A característica da zona.
Leitura
Today
A
na String
Leitura
Tomorrow
A string que identifica amanhã na String
linguagem local.
Leitura
Yesterday
A string que identifica ontem na String
linguagem local.
Leitura
24
string que identifica
linguagem local.
Integer
hoje
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
Propriedade
Descrição
Tipo de Dado
Usado
DoScore
Para newletters criadas usando o Boolean
método
FormatMsgWithDocLinks,
verdadeiro(true) se o resultado
relevante para cada documento
pode ser incluído.
Leitura
Grava
ção
DoSubject
Para newletters criadas usando o Boolean
método
FormatMsgWithDocLinks,
verdadeiro(true) se o subject de
cada
documento
pode
ser
incluído. ( Use SubjectItemName
para definir Qual campo usar
como subject)
Leitura
Grava
ção
SubjectItem
Name
Para newletters criadas usando o String
método
FormatMsgWithDocLinks,
o
nome do campo tratado como o
subject ou título do documento.
Leitura
Grava
ção
Tabela 3.46 Métodos da classe NotesNewsLetter
Método
Descrição
Tipo de Dado de
Retorno
Valor
de
Retorno
Format
Dado a posição de um documento NotesDocument
Docume
na newsletter, cria uma imagem
nt
do documento. Então, cria um
novo documento no banco de
dados fornecido e armazena a
imagem como o corpo do novo
documento.
O
FormatMsg Dado um banco de dados, cria um NotesDocument
WithDoc
documento newsletter no banco
links
de dados.
O
New
O
Cria um novo newsletter.
24.1
NotesNewsletter
novo
docume
nto
criado
docume
nto
newslett
er
novo
newslett
er
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
Propriedade
Descrição
Comment
Um comentário para identificar o String
cronômetro.
Leitura
Grava
ção
Enabled
Se
Leitura
Grava
ção
Interval
O número de segundos para esperar Integer
antes de um alarme disparar.
verdadeiro(true)
cronômetro.
Tipo de Dado
habilita
o Boolean
Usado
Leitura
Grava
ção
Tabela 3.48 Métodos da classe NotesTimer
Método
Descrição
New
Cria um novo cronômetro.
Tipo de Dado de
Retorno
NotesTimer
Valor de Retorno
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á
DoOneMinuteProcessing será chamado a todo minuto.
habilitado,
logo
o
sub
CUIDADO
Não confie muito na precisão do tempo pois outros eventos podem atrasar o tempo
de disparado do evento Alarm.