lotus script

Lotus Script

Por Carlos Abril

Qué es Lotus Script?

• Es un potente lenguaje que permite desarrollar aplicaciones orientado a Objetos.

• LotusScript y su conjunto de herramientas de desarrollo proporcionan un entorno de programación común para todas las aplicaciones de Lotus en todas las plataformas soportadas por el software Lotus (como Windows, AIX, Linux).

Ventajas de Lotus Script

• Superset of BASIC .

• Cross-platform.

• Object-oriented.

• Included in Lotus software applications.

• OLE support.

• Interoperability with other languages.

• Integrated Development Environment

• LotusScript libraries

• Extendable through Lotus Software Extensions (LSXs)

Reglas de construcción

• Cada declaración de script esta compuesta de líneas de texto. Cada elemento de texto es una palabra clave de Lotus Script, operadores, identificadores, literales, o caracteres especiales.

• Puede incluir líneas en blanco sin que afecte el sentido.

• El texto en una línea puede iniciar del lado izquierdo.

• Dentro de una declaración, los elementos estarán separados por espacios en blanco o tabuladores. Espacios extras pueden ser usados para hacer una declaración más legible sin afectar su significado.

• Una declaración, a excepción de un bloque de sentencias, debe aparecer en una sola línea a menos que incluya el carácter de continuación de línea subrayado(_)precedidos por espacios en blanco.

• El carácter de continuación de línea (_) debe aparecer al final de una linea, precedido al menos de un espacio o tabulación.

• Una nueva línea marca el final de una declaración.

• Múltiples declaraciones en una línea deben ser separadas por (:).

Reglas para construcción de cadenas

• Una cadena en Lotus Script puede encerrarse en uno de los siguientes delimitadores:– Un par de doble comillas (“” “”)

“Esta es una cadena entre comillas”

– Un par de barras verticales (||)|esta es una cadena entre barras verticales|

– Con llaves abiertas y cerradas ({}){esta es una cadena entre llaves}

• Cadenas encerradas entre barras verticales pueden separa múltiples líneas.|Una cadena

en dos líneas|.

Reglas para construir identificadores

• Un identificador es el nombre que le da a una variable, constante, tipo, clase, función, procedimiento o propiedad.– El primer carácter debe ser una letra mayúscula o minúscula.

– Los restantes caracteres deben ser letras, dígitos o el carácter subrayado.

– Un sufijo para los tipos de datos(%,&,!,#,@, o $) pueden estar al final, pero no es parte del identificador.

– El tamaño máximo es 40 caracteres, no incluye los sufijos.

– Los nombres pueden ser mayúsculas o minúsculas.

Tipos de datos

• Boolean True(1) o False(0)

• Byte 0 a 255

• Integer

• Long

• Single

• Double

• Currency

• String

Tipos de datos

• Soporta los siguientes tipos de datos y estructuras:

– Array .- conjunto de elementos que tienen el mismo tipo de datos, puede tener hasta 8 dimensiones.

– List .- de una sola dimensión que tienen el mismo tipo de datos.

– Variant .- Un especial tipo de dato que puede contener valores escalares, arreglos, lista, u objetos de referencia. Variant .-puede ser también booleano o fechas.

– User-defined data type .- Tipo de datos definidos por el usuario.

– User-defined class.- definición de clases .

– Object reference .- Punteros a objetos de automatización OLE.

Conversión de tipos de dato

• Lotus Script implícitamente convierte de un tipo de dato a otro en las siguientes situaciones:– Operaciones numéricas .- Operaciones con diferentes tipos de datos

numéricos , Lotus Script convierte los valores a un mismo tipo de dato para evaluación.

– Paso de argumentos .- Cuando un argumento numérico es pasado por valor (by value) a un procedimiento, Lotus Script trata de convertir el valor si no es el tipo de dato esperado. Si el valor es más grande, la operación genera un error.

– Variables Variant.- Cuando un valor es contenido en una variable Variant, Lotus Script trata de convertir el valor a numérico o cadena dependiendo del contexto.

Conversión explícita de tipos de datos

Lotus Script provee varias funciones para convertir explícitamente el valor de un tipo de dato:– Cbool

– CByte

– Ccur

– Cdat

– CDbl

– Cint

– CLng

– CSng

– Cstr

– CVar

Automática conversión de tipos de datos.

• Se puede asignar un valor de un tipo de dato numérico a una variable de un tipo de dato numérico diferente.

• Puede ejecutar operaciones aritméticas o comparaciones que involucran diferentes tipos de datos numéricos.

• Puede incrementar el valor de una variable Variant de algún tipo numérico más allá de los límites permitidos del tipo de dato.

• Puede añadir o concatenar los valores de dos variables variant, uno de los cuales es cadena y el otro es numérico.

Constantes y variables

Se puede manipula varios tipos de datos a través del uso de constantes y variables.

Las constantes y variables tienen un alcance y tiempo de vida.

El alcance se refiere al área en el cual un identificador puede ser referenciado.

El límite se refiere al período durante el cual el identificador esta disponible en la aplicación.

Cuando define una constante o variable, Lotus script asigna un alcance y tiempo de vida.

Alcance de las declaraciones.

• LS reconoce tres tipos de alcance:– Módulo .- Una variable es declarada dentro de un módulo si esta fuera

de algún procedimiento, clase o definición de tipo.

– Procedimiento.- Una variable es declarada dentro de un procedimiento, si es declarada dentro de una función, procedimiento o propiedad. Solamente dentro del procedimiento el nombre de la variable tiene significado. El nombre de la variable es visible en cualquier parte del procedimiento.

– Type o Class .- Una variable esta declarada dentro de un Tipo o Clase, el alcance esta dentro de la definición del tipo o clase.

Clases para acceder a la base de datos Domino

Notes Session

Notes Database

Notes View

Notes DocumentCollection

Notes Document

Notes Item

Clase NotesSession

• Permite crear una sesión de trabajo.

Dim ss as New NotesSession

Propiedades Métodos

CommonUserName .- Nombre común del usuario actual.CurrentDatabase .- Base de datos en la cual esta ejecutando el script.DocumentContextn .- Documento que esta actualmente en memoria.ServerName .- Nombre del servidor donde esta la sesión actual.UserName .- Nombre actual del usuario.

GetEnvironmentString.- Obtiene valores string almacenados en el notes.ini del cliente.GetEnvironmentVaue .- Obtiene los valores numéricos almacenados en el notes.ini del cliente.SetEnvironmenteVar .- Coloca los valores string o numeric en las variables de ambiente (notes.ini)

Clase NotesDatabase• Permite acceder a la base de datos.

Dim ss as New NoteeSession

Dim db as NotesDatabase

Set db = ss.CurrentDatabase


FileName .- Nombre del archivo (nsf).IsOpen n.- Verifica si esta abierta la base de datos.Server .- Indica el servidor donde esta la base.UnprocessedDocument .- todos los documentos que no ha sido procesados en la actual base de datos o vista.Views.- Determina las vistas o carpetas de la actual base de datos

GetDocumentByUNID .- Recupera un documento a través del Universal ID.GetView .- Encuentra una vista o carpeta en la base de datos actual.Search .- Permite hacer busquedasobre la base de datos actual.

Clase NotesView

• Representa una vista o carpeta que contiene documentos.Dim ss as New NotesSession

Dim db as Notesdatabase

Dim view as NotesView

Set db = ss.Currentdatabase

Set view = db.GetView(“Nombre o Alias de una vista”)

Métodos Métodos

GetAllDocumentsByKey .-Recupera todos los documentos basados en una clave de búsqueda.GetDocumentByKey.- recupera un documento basado en una clave de búsqueda.

GetFirstDocument.- Apunta al primer documento de la vista.GetNextDocument .- Permite desplazarse al siguiente documento de la vista.

Clase NotesDocumentCollection

• Representa una collección de documentos de las base de datos.



Dim dc as NotesDocumentCollection

Set db = ss.currentdatabase

Set dc = db.UnprocessedDocument


Count .- Número de documentos por procesar.

GetFirstDocument.- recupera el primer documento de la collección de doc.GetNextDocument .- va al siguiente documento de la collección de doc.

Métodos

DeleteDocument .- borra un documento de la colleción de documentos

Clase NotesDocument

• Representa un documento de la base de datos.Dim ss as New NotesSession



Dim doc as NotesDocument


Set view = db.GetView(“Nombre o Alias de una vista”)

Set doc = view.GetFirstDocument


UniversalID .- Número Universal único del documento.

GetFirstItem .- Apunta a un campo del documento .GetItemValue.- recupera el valor de un doc.ReplaceItemValue .- reemplaza el valor de un doc.Save .- Graba un doc.Send .- Envia un correo.

Clase NotesItem• Permite acceder a un campo del documento.





Dim Item as NotesItem


Set view = db.GetView(“Nombre Vista o carpeta”)

Set doc = view.GetFirstDocument

Set item = doc.GetFirstItem(“NombreCampos”)


Values.- contiene los valores del campo pudiendo ser cadena de caracteres o lista de caracteres

AppendToTextList .- añade un texto a la lista ya existente.Remove.- borra el campo de un documenento.

Ejemplo de recorrer una vista.Dim ss as New NotesSession


Dim View as NotesView



Set db = ss.CurrentDatabase ‘asocia a la variable db la actual base de datos

Set view = db.GetView(“NombreVista”) ‘a la var. View asocia una de las vistas de la base de datos

Set doc = view.GetFirstDocument ‘apunta al primer documento de la vista

While not(doc is nothing) ‘determina si hay un documento asociado a la variable doc

set item = doc.GetFirstItem(“Campo”) ‘obtiene en la variable Item el o los valores de un campo

Forall x In Item.Values ‘es como un For para sacar los valores contenidos en la variable Item

Msgbox x

End Forall

Set doc = view.GetNextDocument(doc) ‘permite avanzar al siguiente documento en la vista

Wend

Modificar un campo en todos los documentos contenidos en una vista

SUPONGAMOS QUE EXISTE EN LOS DOCUMENTOS CONTENIDOS EN UNA VISTA UN CAMPO LLAMADO ESTADO QUE NECESITAMOS CAMBIARLO A FINALIZADO.










set item = doc.ReplaceItemValue(“Estado”,”Finalizado”) ‘Estado es el nombre del campo y Finalizado es el nuevo valor

call doc.save(false,false)


Wend

Enviar por correo información de documentos que cambiaros de estado

Vamos a cambiar el estado de los documento de la vista y vamos a notificar por correo a los creadores de los documentos que se ha realizado el cambio de estado.










set item = doc.ReplaceItemValue(“Estado”,”Finalizado”) ‘Estado es el nombre del campo y Finalizado es el nuevo valor

call doc.save(false,false)

dim docMail as New NotesDocument(db) ‘decimos que vamos a crear un nuevo documento en la actual base de datos

docMail.Form = “Memo” ‘ al nuevo documento le asociamos un formulario en esta caso el Memo que esta asoc. Al correo

docMail.SendTo = doc.Authors(0) ‘Asocio al campo sendTo el autor del documento

docMail.Subject = “Documento que cambio de estado” ‘asocio al campo Asunto(Subject) un texto

docMail.Body = “Se ha modificado el documento ” & cstr(doc.Numero(0))

call docMail.Send(false) ‘se envía el documento sin que se grabe en la base actual el mensaje TRUE hace que se grabe


Wend

Borrar documentos que cumplen una condición

Revisamos que el documento tenga un estado de Borrador y procedemos a borrar los documentos.





Dim docsig as NotesDocument






if doc.Estado(0) = “Borrador” then

set docsig = View.GetNextDocument(doc)

doc.Remove(true)

set doc = docsig

else

set doc = view.GetNextDocument(doc)

end if

Wend

Borrar documentos seleccionados en una vista

Revisamos que el documento tenga un estado de Borrador y procedemos a borrar los documentos.



Dim dc as NotesDocumentCollection




Set dc = db.UnprocessedDocument ‘determina los documentos que están seleccionados en la vista

if dc.Count > 0 then ‘Count determina el número de documentos seleccionados en la vista

for i = 1 to dc.Count

doc = dc. GetNthDocument(i) ‘ accesa al documento

doc.Remove(true) ‘si es TRUE borra físicamente, si es False queda marcado para eliminación

next

End if

Clases para acceder al front-end

.

Notes UIWorkspace

Notes UIDocument

Clase NotesUIWorkspace

• Representa la actual área de trabajo de Lotus.Dim WS as New NotesUIWorkspace


CurrentDatabase .- Representa la base que actualmente esta abierta.CurrentDocument .- Representa el documento que actualmente esta abierto.

DialogBox .- Permite abrir en un cuadro de dialogo un formulario o subformulario. Funciona de igual forma que @DialogBoxEditDocument .- Permite la apertura de un documento que esta en la base.Prompt .- funciona de igual forma que @prompt.

Clase NotesUIDocument• Representa el actual documento que se encuentra abierto en el área de trabajo.

Dim ws as New NotesUIWorkspace

Dim uidoc as NotesDocument

set uidoc = ws.CurrentDocument


Document .- Asocia entre el documento de la base de datos y el documento abierto .EditMode .- Indica si el documento esta en modo de Edición.IsNewDoc .- Indica si el documento es nuevo.

FieldContains.- Chequea si un texto esta contenido en un campo de un documento abierto.FieldGetText .- De un documento abierto recupera el valor almacenado en el texto.FieldSetText .- En un campo de un documento abierto pone un valor.Save .- Graba el documento actualmente abierto.Close n.- Cierra el documento actualmente abierto.

Eventos

PostOpen.- Ubique cualquier script que deba ejecutarse después de abierto el documento.PostModeChange.- Ocurre después de que el documento a cambiado de modo (Edición o Lectura).PostSave .- Ejecuta después de que se grabo el documento

QueryModeChange .- Ocurre antes de que el documento cambie de modo (Edición o Lectura).QuerySave .- Ocurre antes de que el documento sea grabado.

Validar si un documento contiene información antes de grabar

Supones que hay un documento abierto que contiene los campos Nombres, Apellidos, Cedula y EstadoCivil, se desea verificar que haya datos en los campos Nombres, Apellidos y Cedula.

Esta validación la podemos hacer desde el evento QuerySave que tiene ya definidas las variables asociadas a la clase NotesUIDocument, hemos de suponer que se envía la acción de grabar desde un objeto Action que contiene el comando @command([FileSave]).

Sub QuerySave(Source as NotesUIDocument, Continue as variant)

If Source.IsNewDoc then ‘verifico si el documento es nuevo o sea no ha sido grabado nunca.

Dim Mensaje as string

if Trim(Source.FieldGetText(“Nombres”)) = “” then ‘Funcion Trim permite eliminar espacios en blanco

Mensaje = “No ha ingresado los Nombres”

End if

if Trim(Source.FieldGetText(“Apellidos”)) = “” then

if Mensaje = “” then

Mensaje = “No ha ingresado los Apellidos”

else

Mensaje = Mensaje + chr(13) + “No ha ingresado los Apellidos”

endif

End if

if Trim(Source.FieldGetText(“Cedula”)) = “” then

‘Identico la validación al campo Apellidos

End if

if Mensaje <> “” then

MsgBox Mensaje

Continue = False ‘ Cuando Continue es FALSE detiene el proceso de grabado similar @failure

end if

End if

End Sub

Cómo evitar que un documento se Edite de acuerdo al valor de un campo?

Supongamos que los documento van cambiando de estado y el estado final es Cerrado, entonces se desea evitar que un documento sea editado si el estado ya esta Cerrado.

QueryModeChange( Source as NotesUIDocument , Continue as Variant )

if not(Source.IsNewDoc) then ‘verifico que el documento no sea nuevo

if Source.FieldGetText(“Estado”) = “Cerrado” then ‘verifico el estado del documento

MsgBox “Documento no puede ser editado”

Continue = false

end if

end if

End Sub

Notificar al propietario de un documento que ha sido abierto y si es Editado creamos un documento con

información al estilo logSE EJECUTA SOLO SI EL DOCUMENTO EXISTE SI NO EXISTE NO EJECUTA EL SCRIPT

Sub Postopen(Source As Notesuidocument)

if not(Source.IsNewDoc) then

dim ss as New NotesSession

dim db as NotesDatabase

dim doc as NotesDocument

dim docMail as NotesDocument

set db = ss.Currentdatabase

set doc = Source.Document ‘relaciono el documento del back-end con el doc editable

set docMail = new NotesDocument(db)

docMail.Form = “Memo”

docMail.SendTo = doc.Authors(0)

docMail.Subject = “Su documento ha sido abierto”

docMail.Body = “El documento ha sido abierto el ” + cstr(now) + “ por el usuario” + ss.UserName

call docMail.send(false)

end if

EndSub

Creamos un documento LOG que indique que un documento ha sido editado

SE EJECUTA SOLO SI EL DOCUMENTO EXISTE SI NO EXISTE NO EJECUTA EL SCRIPT

Sub PostModeChange(Source As Notesuidocument)

if not(Source.IsNewDoc) then

if Source.EditMode then

dim ss as New NotesSession

dim db as NotesDatabase

dim doc as NotesDocument

dim docLog as NotesDocument

set db = ss.Currentdatabase

set doc = Source.Document ‘relaciono el documento del back-end con el doc editable

set docLog = new NotesDocument(db)

docLog.Form = “LOG”

docLog.QuienEdito = ss.UserName

docLog.FechaApertura = now

call docLog.save(false,false)

end if

end if

EndSub

lotus script

Technology