Library part in EGL source format

You declare a library part in an EGL source file, which is described in EGL source format.

An example of a library part is as follows:
Library CustomerLib3 

	// Use declarations
	Use StatusLib;
	
	// Data Declarations
	exceptionId ExceptionId ;
	
	// Retrieve one customer for an email
	//   In:  customer, with emailAddress set
	//   Out: customer, status
	Function getCustomerByEmail ( customer CustomerForEmail, status int )
		status = StatusLib.success;
		try
			get customer ;  
		onException 
			exceptionId = "getCustomerByEmail" ; 
			status = sqlCode ;
		end
		commit();
	end	
	
	// Retrieve one customer for a customer ID
	//   In: customer, with customer ID set
	//   Out: customer, status
	Function getCustomerByCustomerId ( customer Customer, status int )
		status = StatusLib.success;
		try
			get customer ;  
		onException 
			exceptionId = "getCustomerByCusomerId" ; 
			status = sqlCode ;
		end
		commit();
	end	
	
	// Retrieve multiple customers for an email
	//   In: startId
	//   Out: 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

The diagram of a library part is as follows:


Syntax diagram for a library part
Library libraryPartName ... end
Identifies the part as a library part and specifies the name. If you do not set the alias property (as described later), the name of the generated library is libraryPartName.

For other rules, see Naming conventions.

type BasicLibrary, type NativeLibrary, type ServiceBindingLibrary
Indicates the library type:
  • A basic library (type BasicLibrary) contains EGL-written functions and values for runtime use in other EGL logic; for details, see Library part of type BasicLibrary.
  • A native library (type NativeLibrary) acts as an interface for an external DLL; for details, see Library part of type NativeLibrary
  • A service binding library (type ServiceBindingLibrary) indicates how a variable of type Interface or Service accesses a service at run time; for details, see Library part of type ServiceBindingLibrary

The library is of type BasicLibrary by default.

libraryProperties
The library properties are as follows:
  • alias
  • allowUnqualifiedItemReferences
  • callingConvention (which is available only in libraries of type NativeLibrary)
  • dllName (which is available only in libraries of type NativeLibrary)
  • handleHardIOErrors
  • includeReferencedFunctions
  • localSQLScope
  • messageTablePrefix
  • runtimeBind (which is available only in libraries of type ServiceBindingLibrary)
  • throwNrfEofExceptions

All are optional:

  • alias = "alias" identifies a string that is incorporated into the names of generated output. If you do not set the alias property, the program-part name is used instead.
  • allowUnqualifiedItemReferences = no, allowUnqualifiedItemReferences = yes specifies whether to allow your code to reference structure items but to exclude the name of the container, which is the data table, record, or form that holds the structure item. Consider the following record part, for example:
      Record aRecordPart type basicRecord
        10 myItem01 CHAR(5);
        10 myItem02 CHAR(5);
      end
    The following variable is based on that part:
      myRecord aRecordPart;
    If you accept the default value of allowUnqualifiedItemReferences (no), you must specify the record name when referring to myItem01, as in this assignment:
      myValue = myRecord.myItem01;
    If you set the property allowUnqualifiedItemReferences to yes, however, you can avoid specifying the record name:
      myValue = myItem01;

    It is recommended that you accept the default value, which promotes a best practice. By specifying the container name, you reduces ambiguity for people who read your code and for EGL.

    EGL uses a set of rules to determine the area of memory to which a variable name or item name refers. For details, see References to variables and constants.

  • As used in a library of type NativeLibrary, callingConvention = I4GL specifies how the EGL runtime passes data between two kinds of code:
    • The EGL code that invokes the library function; and
    • The function in the DLL being accessed.

    The only value now available for callingConvention is I4GL. For additional details, see Library part of type NativeLibrary.

  • As used in a library of type NativeLibrary, dllName specifies the DLL name, which is final; it cannot be overridden at deployment time. If you do not specify a value for the library property dllName, you must specify the DLL name in the Java™ runtime property vgj.defaultI4GLNativeLibrary.

    For additional details, see Library part of type NativeLibrary.

  • handleHardIOErrors = yes, handleHardIOErrors = no sets the default value for the system variable VGVar.handleHardIOErrors. The variable controls whether a program continues to run after a hard error has occurred on an I/O operation in a try block. The default value for the property is yes, which sets the variable to 1.

    For other details, see VGVar.handleHardIOErrors and Exception handling.

  • includeReferencedFunctions = no, includeReferencedFunctions = yes indicates whether the library contains a copy of each function that is neither inside the library nor in a library accessed by the current library. The default value is no, which means that you can ignore this property if all functions that are to be part of this library are inside the library.

    If the library is using shared functions that are not in the library, generation is possible only if you set the property includeReferencedFunctions to yes.

  • localSQLScope = yes, localSQLScope = no indicates whether identifiers for SQL result sets and prepared statements are local to the library code during invocation by a program or pageHandler, as is the default. If you accept the value yes, different programs can use the same identifiers independently, and the program or pageHandler that uses the library can independently use the same identifiers as are used in the library.

    If you specify no, the identifiers are shared throughout the run unit. The identifiers created when the SQL statements in the library is invoked are available in other code that invokes the library, although the other code can use localSQLScope = yes to block access to those identifiers. Also, the library may reference identifiers created in the invoking program or pageHandler, but only if the SQL-related statements were already run in the other code and if the other code did not block access.

    The effects of sharing SQL identifiers are as follows:
    • You can open a result set in one code and get rows from that set in another
    • You can prepare an SQL statement in one code and run that statement in another

    In any case, the identifiers available when the program or pageHandler accesses the library are available when the same program or pageHandler accesses the same or another function in the same library.

  • msgTablePrefix = "prefix" specifies the first one to the four characters in the name of a data table that is used as a message table. (The message table is available to forms that are output by library functions.) The other characters in the name correspond to one of the national language codes listed in DataTable part in EGL source format.
  • runtimeBind = no, runtimeBind = yes is valid only in library parts of type ServiceBindingLibrary and indicates whether the service binding information is saved to a library-specific property file that can be changed at deployment time and is accessed only at run time. For details, see Library part of type ServiceBindingLibrary.
  • throwNrfEofExceptions = no, throwNrfEofExceptions = yes specifies whether a soft error causes an exception to be thrown. The default is no. For background information, see Exception handling.
useDeclaration
Provides easier access to a data table or library, and is needed to access forms in a form group. For details, see Use declaration.
private
Indicates that the variable, constant, or function is unavailable outside the library. If you omit the term private, the variable, constant, or function is available.

You cannot specify private for a function in a library of type NativeLibrary.

fieldName
Name of a primitive field. For the rules of naming, see Naming conventions.
primitiveType
The primitive type of a field or (in relation to an array) the primitive type of an array element.
length
The parameter's length or (in relation to an array) the length of an array element. The length is an integer that represents the number of characters or digits in the memory area referenced either by fieldName or (in the case of an array) dynamicArrayName.
decimals
For a numeric type, you may specify decimals, which is an integer that represents the number of places after the decimal point. The maximum number of decimal positions is the smaller of two numbers: 18 or the number of digits declared as length. The decimal point is not stored with the data.
"dateTimeMask"
For TIMESTAMP and INTERVAL types, you may specify "dateTimeMask", which assigns a meaning (such as "year digit") to a given position in the datetime value. The mask is present with the data at run time.
dataItemPartName
The name of a dataItem part that is visible to the program. For details on visibility, see References to parts.

The part acts as a model of format, as described in Typedef.

recordName
Name of a record. For the rules of naming, see Naming conventions.
recordPartName
Name of a record part that is visible to the program. For details on visibility, see References to parts.

The part acts as a model of format, as described in Typedef.

constantName literal
Name and value of a constant. The value is either a quoted string or a number. For the rules of naming, see Naming conventions.
itemProperty
An item-specific property-and-value pair, as described in Overview of EGL properties and overrides.
recordProperty
A record-specific property-and-value pair. For details on the available properties, see the reference topic for the record type of interest.

A basic record has no properties.

itemName
Name of a record field whose properties you wish to override. See Overview of EGL properties and overrides.
arrayName
Name of a dynamic array. If you use this option, the other symbols to the right (dataItemPartName, primitiveType, and so on) refer to each element of the array.
size
Number of elements in the array. If you specify the number of elements, the array is static; otherwise, the array is dynamic.
functionPart
A function. No parameter in the function can be of a loose type. For details, see Function part in EGL source format.
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.