gmplLibraryStatement
Library Statement Summary
Section titled “Library Statement Summary”Library is a nonterminal, declaration statement that occurs primarily in reference scripts. It Introduces a library interface description file. The term “library” refers to an external component like a dll, or an ocx, or an olb, or a tlb whose components are referenced by a source code but not defined within the source code. Contemporary languages are extensible. Components can be added to the language processing environment that can be treated in exactly the same manner as core components in the language. These components have to be described to gmBasic. This is done via a Library specification. The term Interface refers to “those aspects of a language extension that can be referenced by statements in programs that use that extension”. Historically, these referenced aspects of language extensions were simply libraries of subprograms that could be called by other programs. Though external components are far more complex now Library, remains the cover term.
Library description files are initially authored by gmBasic in one of two contexts. First, are the translations of IDL files describing COM components stored in the system and referenced by the source code being translated. These are called DescriptionFiles. Second, when gmBasic translates a VB6 project that can be referenced by other codes as an external reference, it also writes a description called a LocalDecriptionFile.
The attributes of the Library statement are as follows:
| Attribute | Description |
|---|---|
| Id | This attribute simply identifies the external library being defined via its local filename like mso.dll or msword9.olb or mscomctl.ocx or msado20.tlb. For VB6 projects its source is the exename32 value from the project file. |
| Name | This attribute is the identifier of the library from the IDL. It becomes the namespace for the library in the code. For VB6 projects, it is the Name value from the project file. |
| Uuid | This attribute is the uuid specified in the IDL file. For VB6 projects the value of this attribute is controlled by the Select ProjectReference author flag. This attribute is often omitted. |
| Type | This attribute specifies the type of external component that the library is. Its entries are from the LibraryType enumeration. Its values are Internal, Native, ActiveX, or LocalImport. For IDL libraries those with ocx extensions become ActiveX and the others are LocalImport. For VB6 projects it is always Native. |
| Space | This deprecated attribute supplies an identifier to be used for the library in the target language. |
| Source | This attribute is used for IDL authored libraries to document their source file name. It is not used by gmBasic beyond that. |
| Location | This attribute specifies the target location of the actual external component being described by the declarations. It is typically authored using the %library% gmSL meta variable — for example %library%\Interop.ADODB.dll. This assures that when the target project files are authored they will be reference as being in the actual library location for the migration set. Setting this attribute to DoNotDeclare blocks the inclusion of references to the external in the target project files. |
| Axlocation | This attribute is used for IDL authored ActiveX libraries that are to be used as COM components. It declares the pathname of the AxInterop library. |
| Netversion | This attribute is used for IDL authored libraries to document their version, if specified. It is not used by gmBasic beyond that. |
| MigName | This attribute is used to specify the namespace to be used for the library, as opposed to the source namespace name, in the authored code. |
| Assemblyname | This attribute is the assembly name to be used for the library in authored project files for Native libraries. |
| IdfStatus | This attribute specifies how references to the library are to be treated. There five possible settings — None, Build, Migrate, Interop and External. When the Buildfile Select is on then the default IdfStatus is Build. When BuildFile is off then the default IdfStatus is Migrate. The Interop setting is an intermediate one which says that any Mig files associated with the reference should be ignored. The External status blocks the authoring of stubs completely. |
| ImplicitByRef | This On/Off attribute controls how references to ref parameters in the library are handled. When this attribute is set On for the library, the tool will assume that the .NET compiler will be handling ref arguments implicitly. For the purposes of ByRef optimization, the analyzer will still treat these as ByRef, but the author will not emit the ref keyword in the calls and it will not generate temporary arguments. This means that constants and expressions can be passed to ref parameters in a readable way. Note that when the tool is generating stubs for a library with this attribute On, the stubs for that library will not have ref parameters. |
The substatements of the Library statement are as follows:
| Substatement | Description |
|---|---|
| Importlib | A local substatement that declares an external reference made by the library. |
| Enumeration | A declaration statement that defines an enumeration within the library. |
| Class | A declaration statement that defines a class within the library. |
| Structure | A declaration statement that defines a structure within the library |
| Union | A declaration statement that defines a union within the library |
| Typedef | A declaration statement that defines a typedef within the library. |
| Coclass | A declaration statement that defines a class that is actually defined as the union of a set of classes |
| Migclass | A refactoring statement that defines a class containing components needed to migrate the library to the target environment. |
The script errors associated with the Library statement are as follows:
| Error | Description |
|---|---|
| 1123 | Library command missing required id attribute. |
| 1124 | Unable to store Library id: %1d |
| 1125 | Library command missing required name attribute. |
| 1126 | Unable to store Library id: %1d |
| 1127 | The library pattern type %1d is not defined. |
| 1128 | Importlib command missing required id attribute. |
| 1129 | The following library record is not recognized: %1d |
Importlib Library Substatement Summary
Section titled “Importlib Library Substatement Summary”Importlib is a terminal substatement of the Library statement. Just as VB6 projects and ASP web sites reference external components, so do external components. This statement declares an external component used by the library being loaded. The ImportLib must appear at the beginning of the Library substatements since its components will be referenced by components in the library. The imported library itself is treated no differently than any other external reference when it is loaded, including the search though the selected search locations. If an import is already loaded, it is not loaded again.
The attributes of the Importlib substatement are as follows:
| Attribute | Description |
|---|---|
| Id | This attribute specifies the library identifier of the library whose description is to be imported. |