Componente de biblioteca en formato fuente EGL

Un componente de biblioteca (library) se declara en un archivo fuente EGL, como se describe en el apartado Formato fuente EGL.

Este es un ejemplo de un componente de biblioteca:
Library CustomerLib3 

	// Declaraciones Use
	Use StatusLib;
	
	 // Declaraciones de datos
	exceptionId ExceptionId ;
	
	// Recuperar un cliente para un correo electrónico
	//   Entrada: cliente, con emailAddress establecido
	//   Salida: cliente, estado
	Function getCustomerByEmail ( customer CustomerForEmail, status int )
		status = StatusLib.success;
		try
			get customer ;  
		onException 
			exceptionId = "getCustomerByEmail" ; 
			status = sqlCode ;
		end
		commit();
	end	
	
	// Recuperar un cliente para un ID de cliente
	//   Entrada: cliente, con ID de cliente establecido
	//   Salida: cliente, estado
	Function getCustomerByCustomerId ( customer Customer, status int )
		status = StatusLib.success;
		try
			get customer ;  
		onException 
			exceptionId = "getCustomerByCusomerId" ; 
			status = sqlCode ;
		end
		commit();
	end	
	
	// Recuperar varios clientes para un correo electrónico
	//   Entrada: startId
	//   Salida: customers, status
	Function getCustomersByCustomerId 
( startId CustomerId, customers Customer[], status int )
		status = StatusLib.success;
		try
			get customers usingKeys startId ;  
		onException 
			exceptionId = "getCustomerForEmail" ; 
			status = sqlCode ;
		end
		commit();
	end	
	
end

El diagrama de un componente de biblioteca es el siguiente:


Diagrama de sintaxis de un componente library
Library nombreComponenteBiblioteca ... end
Identifica el componente como un componente de biblioteca y especifica el nombre. Si no establece la propiedad alias (como se describe más adelante), el nombre de la biblioteca generada es libraryPartName.

Para conocer otras reglas, consulte Convenios de denominación.

type BasicLibrary, type NativeLibrary, type ServiceBindingLibrary
Indica el tipo de biblioteca:
  • Una biblioteca básica (type BasicLibrary) contiene funciones escritas por EGL y valores para tiempo de ejecución en otra lógica de EGL; para conocer más detalles, consulte la sección Componente de biblioteca de tipo BasicLibrary.
  • Una biblioteca nativa (type NativeLibrary) actúa como una interfaz para una DLL externa; para conocer más detalles, consulte la sección Componente de biblioteca de tipo NativeLibrary
  • Una biblioteca de enlaces de servicio (tipo ServiceBindingLibrary) indica cómo accede una variable de tipo interfaz o servicio a un servicio durante la ejecución; para obtener detalles, consulte la sección Componente de biblioteca de tipo ServiceBindingLibrary

Por omisión, la biblioteca es de tipo BasicLibrary.

propiedadesBiblioteca
Las propiedades de biblioteca son las siguientes:
  • alias
  • allowUnqualifiedItemReferences
  • callingConvention (que está disponible solo en bibliotecas de tipo NativeLibrary)
  • dllName (que está disponible solo en bibliotecas de tipo NativeLibrary)
  • handleHardIOErrors
  • includeReferencedFunctions
  • localSQLScope
  • messageTablePrefix
  • runtimeBind (que está disponible solo en bibliotecas de tipo ServiceBindingLibrary)
  • throwNrfEofExceptions

Todas son opcionales:

  • alias = "alias" identifica una serie que se incorpora a los nombres de salida generada. Si no establece la propiedad alias, en su lugar se utiliza el nombre del componente programa .
  • allowUnqualifiedItemReferences = no, allowUnqualifiedItemReferences = yes especifica si debe permitirse que el código haga referencia a elementos de estructura, pero excluyendo el nombre del contenedor, que es la tabla de datos, registro o formulario que contiene el elemento de estructura. Observe, por ejemplo, el siguiente componente de registro:
      Record ExampleRecordPart type basicRecord
        10 myItem01 CHAR(5);
        10 myItem02 CHAR(5);
      end
    La siguiente variable está basada en ese componente:
      myRecord ExampleRecordPart;
    Si acepta el valor por omisión de allowUnqualifiedItemReferences (no), debe especificar el nombre de registro al hacer referencia a myItem01, como en esta asignación:
      myValue = myRecord.myItem01;
    Si establece la propiedad allowUnqualifiedItemReferences como yes, no obstante, puede evitar especificar el nombre de registro:
      myValue = myItem01;

    Se recomienda aceptar el valor por omisión, que ofrece un mejor resultado. Especificando el nombre de contenedor, se reduce la ambigüedad para quien lea su código y para EGL.

    EGL utiliza un conjunto de reglas para determinar el área de la memoria a la que hace referencia un nombre de variable o un nombre de elemento. Para conocer detalles, consulte Referencias a variables y constantes.

  • Tal como se utiliza en una biblioteca de tipo NativeLibrary, callingConvention = I4GL especifica cómo el entorno de ejecución de EGL pasa datos entre dos clases de código:
    • El código EGL que invoca la función de biblioteca
    • La función de la DLL a la que se accede.

    El único valor disponible para callingConvention es I4GL: Para conocer más detalles, consulte la sección Componente de biblioteca de tipo NativeLibrary.

  • Tal como se utiliza en una biblioteca de tipo NativeLibrary, dllName especifica el nombre de DLL, que es final; no puede alterarse temporalmente en tiempo de despliegue. Si no especifica un valor para la propiedad de biblioteca dllName, debe especificar el nombre de DLL en la propiedad de tiempo de ejecución Java vgj.defaultI4GLNativeLibrary.

    Para conocer más detalles, consulte la sección Componente de biblioteca de tipo NativeLibrary.

  • handleHardIOErrors = yes, handleHardIOErrors = no establece el valor predeterminado para la variable del sistema VGVar.handleHardIOErrors. La variable controla si un programa continúa ejecutándose después de que se haya producido un error grave en una operación de E/S en un bloque try. El valor predeterminado de la propiedad es yes, que establece la variable en 1.

    Para obtener más detalles, consulte VGVar.handleHardIOErrors y Manejo de excepciones.

  • includeReferencedFunctions = no, includeReferencedFunctions = yes indica si la biblioteca contiene una copia de cada función que no está ni dentro de la biblioteca ni en una biblioteca a la que accede la biblioteca actual. El valor por omisión es no, lo que significa que puede pasar por alto esta propiedad si todas las funciones que deben formar parte de esta biblioteca se encuentran dentro de la misma.

    Si la biblioteca utiliza funciones compartidas que no están en ella, la generación sólo es posible si establece la propiedad includeReferencedFunctions en yes.

  • localSQLScope = yes, localSQLScope = no indica si los identificadores de los conjuntos de resultados y sentencias preparadas de SQL son locales para el código de biblioteca durante la invocación por un programa o pageHandler, lo que constituye el valor predeterminado. Si acepta el valor yes, distintos programas pueden utilizar los mismos identificadores independientemente y el programa o pageHandler que utiliza la biblioteca puede utilizar independientemente los mismos identificadores que se utilizan en la biblioteca.

    Si especifica no, los identificadores se comparten en toda la unidad de ejecución. Los identificadores creados cuando las sentencias SQL de la biblioteca se invocan están disponibles en otro código que invoca la biblioteca, aunque el otro código puede utilizar localSQLScope = yes para bloquear el acceso a esos identificadores. Además, la biblioteca puede hacer referencia a los identificadores creados en el programa invocante o pageHandler, pero solo si las sentencias relacionadas con SQL se hubieran ejecutado ya en el otro código y si el otro código no bloqueara el acceso.

    Los efectos de compartir identificadores SQL son los siguientes:
    • Puede abrir un conjunto de resultados en un código y obtener filas de ese conjunto en otro
    • Puede preparar una sentencia SQL en un código y ejecutar esa sentencia en otra

    En cualquier caso, los identificadores disponibles cuando el programa o pageHandler accede a la biblioteca están disponibles cuando el mismo programa o pageHandler accede a la misma o a otra función de la misma biblioteca.

  • msgTablePrefix = "prefijo" especifica el primero de los cuatro caracteres del nombre de una tabla de datos que se utiliza como tabla de mensajes. (La tabla de mensajes está disponible para los formularios que son la salida de funciones de biblioteca.) Los demás caracteres del nombre corresponden a uno de los códigos de idioma nacional listados en Componente DataTable en formato fuente EGL.
  • runtimeBind = no, runtimeBind = yes sólo es válido en componentes de biblioteca de tipo ServiceBindingLibrary e indica si la información de enlace de servicio se guarda en un archivo de propiedades específico de biblioteca que puede cambiarse durante el despliegue y al que sólo se accede durante la ejecución. Para conocer más detalles, consulte la sección Componente de biblioteca de tipo ServiceBindingLibrary.
  • throwNrfEofExceptions = no, throwNrfEofExceptions = yes especifica si un error leve provoca el lanzamiento de una excepción. El valor por omisión es no. Para obtener información, consulte la sección Manejo de excepciones.
declaraciónUso
Proporciona fácil acceso a una tabla de datos o biblioteca y es necesario para acceder a formularios de un grupo de formularios. Para conocer detalles, consulte Declaración Use.
private
Indica que la variable, constante o función no está disponible fuera de la biblioteca. Si omite el término private, la variable, constante o función estará disponible.

No puede especificar private para una función en una biblioteca de tipo NativeLibrary.

nombreCampo
Nombre de un campo primitivo. Para conocer las reglas de denominación, consulte Convenios de denominación.
tipoPrimitivo
El tipo primitivo de un campo o, en relación con una matriz, el tipo primitivo de un elemento de matriz.
longitud
La longitud del parámetro o (en relación con una matriz) la longitud de un elemento de matriz. La longitud es un entero que representa el número de caracteres o dígitos en el área de memoria a la que hace referencia nombreCampo o (en el caso de una matriz) nombreMatrizDinámica.
decimales
Para un tipo numérico puede especificar decimales que es un entero que representa el número de posiciones después de la coma decimal. El número máximo de posiciones decimales es el menor de dos números: 18 o el número de dígitos declarado como longitud. La coma decimal no se almacena con los datos.
"máscaraFechaHora"
Para los tipos TIMESTAMP e INTERVAL puede especificar máscaraFechaHora", que asigna un significado (como por ejemplo "dígito de año") a una posición determinada en el valor de fecha y hora. La máscara está presente con los datos durante la ejecución.
nombreComponenteElementoDatos
El nombre de un componente dataItem que es visible al programa. Para conocer detalles sobre la visibilidad, consulte Referencias a componentes.

El componente actúa como un modelo de formato, tal como se describe en Typedef.

nombreRegistro
El nombre de un registro. Para conocer las reglas de denominación, consulte Convenios de denominación.
nombreComponenteRegistro
El nombre de un componente de registro que es visible al programa. Para conocer detalles sobre la visibilidad, consulte Referencias a componentes.

El componente actúa como un modelo de formato, tal como se describe en Typedef.

nombreConstante literal
El nombre y valor de una constante. El valor puede ser una serie entrecomillada o un número. Para conocer las reglas de denominación, consulte Convenios de denominación.
propiedadElemento
Un par de propiedad y valor específico de un elemento, tal como se describe en Visión general de propiedades y alteraciones temporales de EGL.
propiedadRegistro
Un par de propiedad y valor específico de un registro. Para conocer detalles sobre las propiedades disponibles, consulte el tema de referencia para el tipo de registro específico.

Un registro básico no tiene propiedades.

nombreElemento
Nombre de un campo de registro cuyas propiedades desea alterar temporalmente. Consulte Visión general de propiedades y alteraciones temporales de EGL.
nombreMatriz
Nombre de una matriz dinámica. Si utiliza esta opción, los demás símbolos a la derecha (nombreComponenteElementoDatos, tipoPrimitivo y demás) hacen referencia a cada elemento de la matriz.
tamaño
El número de elementos de la matriz. Si especifica el número de elementos, la matriz es estática; de lo contrario, la matriz es dinámica.
componenteFunción
Una función. Ningún parámetro de la función puede ser de un tipo suelto. Para conocer detalles, consulte Componente de función en formato fuente EGL.
Comentarios
(C) Copyright IBM Corporation 2000, 2005. Reservados todos los derechos.