Software of the Month Club 1995 December

home *** CD-ROM | disk | FTP | other *** search

/ Software of the Month Club 1995 December / SOFM_Dec1995.bin / pc / os2 / vpascal / vp.txt < prev

Wrap

Text File | 1995-10-31 | 32KB | 788 lines

TABLE OF CONTENTS ~~~~~~~~~~~~~~~~~ 1. Getting started 1.1 Compilation process 1.2 Linker module definition file 1.3 Target platforms 1.4 OS/2 API interface units 2. Borland Pascal compatibility issues 2.1 Data types 2.2 Pointer types 2.3 Integer expressions 2.4 Standard unit implementation differences 2.4.1 System unit 2.4.2 Dos unit 2.4.3 WinDos unit 2.4.4 Crt unit 2.4.5 WinCrt and Strings unit 2.4.6 32-bit Turbo Vision for OS/2 2.5 Compiler directives 2.6 Built-in assembler 2.7 Register usage 2.7.1 Embedded ASM statements 2.7.2 Assembler procedures and functions 2.8 Code generation differences 2.9 Import and export 2.10 Inline statements and inline subroutines 3. New Virtual Pascal features 3.1 Calling conventions 3.2 Naming convention 3.3 Pure interface units 3.4 Direct port access 3.5 Import 3.6 Export 3.7 Presentation Manager resources 3.8 Writing OS/2 Dynamic Link libraries 3.8.1 Subroutine libraries 3.8.2 Subsystems 1. GETTING STARTED ~~~~~~~~~~~~~~~~~~ There is no documentation in this beta release other than online help system of the IDE and this file. This documentation is addressed to those who are familiar with Borland Pascal. If you are a user of the Borland Pascal, you may have only few problems, because VP and BP are very much alike. Even error messages have the same numbers and spellings. This document reflects the main differences between Virtual Pascal and Borland Pascal v7.0 and introduces new Virtual Pascal features. 1.1 COMPILATION PROCESS ~~~~~~~~~~~~~~~~~~~~~~~~ Borland Pascal compiles source code to the object code with a compiler version and target platform specific format. For a unit it generates .TPU/.TPP/.TPW files (.DCU in Delphi Pascal Compiler) that contains object code and interface symbol information. Virtual Pascal generates two kind of files: - containing object code (.OBJ, .LIB or ASM); - containing interface symbol information (.VPI). The following picture describes the compilation process: ┌──────────────┐ ┌────────>─┤ UnitName.OBJ │ $SmartLink- │ │ UnitName.VPI │ $Asm- │ └──────────────┘ │ ┌──────────────┐ ┌──────────────┐ │ │ UnitName.OBJ │ $SmartLink- │ UnitName.PAS ├─┼────────>─│ UnitName.ASM │ $Asm+ └──────────────┘ │ │ UnitName.VPI │ │ └──────────────┘ │ ┌──────────────┐ │ │ UnitName.LIB │ $SmartLink+ └────────>─│ UnitName.VPI │ └──────────────┘ ┌─────────────────┐ ┌─────────────────┐ │ ProgramName.OBJ │ │ ProgramName.PAS ├──┬────>─┤ ProgramName.ASM │ $Asm+ └─────────────────┘ │ │ ProgramName.LNK │ │ └─────────────────┘ │ ┌─────────────────┐ └────>─┤ ProgramName.OBJ │ $Asm- │ ProgramName.LNK │ └─────────────────┘ ┌─────────────────┐ ┌─────────────────┐ │ LibraryName.OBJ │ │ LibraryName.PAS ├──┬────>─┤ LibraryName.ASM │ $Asm+ └─────────────────┘ │ │ LibraryName.LNK │ │ └─────────────────┘ │ ┌─────────────────┐ └────>─┤ LibraryName.OBJ │ $Asm- │ LibraryName.LNK │ └─────────────────┘ .ASM file is a readable 386 assembly source file which can be compiled by MASM 6.0a+ or TASM 3.0+. .OBJ and .LIB files are standard Intel Object Module Format (OMF) object and library files. They can be linked by any 32-bit OMF linker, which is capable of generating linear executables (LX) for OS/2. By default, Virtual Pascal uses LINK386 supplied with OS/2. Note, that if a unit has no code (it is simply used to define constants and types), then no object code is generated and there would be no .OBJ or .LIB file for it. .LNK file is a linker response file which should be passed to the linker. It contains the list of object and library files, module definition file name (if compiler found it) and linker map file name (VPC: if /G command line option is specified, IDE: Linker│Map file active button is other than None). .VPI file is a Virtual Pascal Interface file. It contains interface symbol information. Only .VPI file format is compiler version dependent. For directions of how to distribute object code without source, see PURE INTERFACE UNITS section. 1.2 LINKER MODULE DEFINITION FILE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Borland Pascal has a built-in linker, that is why it passes additional information (segment attributes, description text, etc) to the linker by means of compiler directives. Virtual Pascal uses standalone linker, so you can use linker module definition file to supply this additional information about your application. You must use module definition file to create dynamic link libraries. Module definition file should be located in the same directory as a primary file of the program or library, and must have the same name, but a .DEF extension. A module definition file is a plain text file that describes the names, segment attributes, exports, imports, and other characteristics of an application or library. It contains one or more module statements. Here are the brief summary of the module statements: BASE = BaseAddress CODE [PRELOAD | LOADONCALL] [EXECUTEONLY | EXECUTEREAD] [IOPL | NOIOPL] [CONFORMING | NONCONFORMING] DATA [PRELOAD | LOADONCALL] [READONLY | READWRITE] [NONE | SINGLE | MULTIPLE] [SHARED | NONSHARED] [IOPL | NOIOPL] DESCRIPTION 'text' EXETYPE OS2 EXPORTS ExportName [= InternalName][@Ordinal][RESIDENTNAME | NONAME] [StackParams] IMPORTS [InternalName =] ModuleName.EntryName | ModuleName.Ordinal LIBRARY [LibraryName] [INITGLOBAL | INITINSTANCE] [TERMGLOBAL | TERMINSTANCE] NAME [ApplicationName] [WINDOWAPI | WINDOWCOMPAT | NOWINDOWCOMPAT] OLD `filename.DLL' SEGMENTS ['] Name ['] [ CLASS ['ClassName']] [PRELOAD | LOADONCALL] [READONLY | READWRITE] [EXECUTEONLY | EXECUTEREAD] [IOPL | NOIOPL] [CONFORMING | NONCONFORMING] [SHARED | NONSHARED] STUB `FileName.EXE' | NONE 1.3 TARGET PLATFORMS ~~~~~~~~~~~~~~~~~~~~ Virtual Pascal can generate code for either OS/2 full screen application or Presentation Manager application. Virtual Pascal combines all three Borland Pascal target platforms into one. You should specify the type of the application to be generated by the Linker│Application radio buttons or specify application type in the NAME statement of the module definition file (if you use linker other than LINK386). 1.4 OS/2 API interface units ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It is a good practice to use standard Borland Pascal unit procedures and functions for your programs. If you need OS/2 specific functions you can use OS/2 API interface units to call them directly. There are four interface units supplied: Os2Def: Contains common definitions for OS/2 base and Presentation Manager API. Os2Base: Contains API functions and type declarations for writing OS/2 base applications. It also contains 16-bit API function prototypes for writing full screen applications (KBD/VIO/MOU/MON/NLS calls). Os2PmApi: Contains Presentation Manager interface constants, types and function prototypes. Os2Rexx: Contains an interface to OS/2 REXX interpreter. 2. BORLAND PASCAL COMPATIBILITY ISSUES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Unlike Borland Pascal, Virtual Pascal generates 32-bit code. The main differences between Borland Pascal and Virtual Pascal are due to this fact. To maintain backward 16-bit compatibility, Virtual Pascal uses some tricks described in this chapter. 2.1 DATA TYPES ~~~~~~~~~~~~~~ All built-in data types have the same name, size and meaning, except for two floating point types (Real and Extended). Virtual Pascal uses only coprocessor types, that is why Real and Double types are identical. Extended type is 10-byte floating point coprocessor type, but occupies 12 bytes to maintain double word alignment. Built-in assembler accepts 12-byte sized variables as TBYTE operands. It is not efficient to use on true 32-bit processor 16-bit integer variables. That is why to maintain backward 16-bit compatibility, in 32-bit programs written in Virtual Pascal, it is recommended to include USE32 unit into USES clause of each unit. USE32 unit redefines built-in 16-bit integer types Integer and Word as 32-bit Longint type (see source code for the USE32 unit: \VP\SOURCE\RTL\USE32.PAS). If you really need to use 16-bit integers, use SmallInt and SmallWord types instead of Integer and Word, or use fully qualified identifiers: System.Integer and System.Word. 2.2 POINTER TYPES ~~~~~~~~~~~~~~~~~ Virtual Pascal uses 32-bit flat memory model. Pointers in Virtual Pascal have the same size (4 bytes) but denote 32-bit flat memory address rather than 16-bit segment (or selector) and 16-bit offset. As a result, Mem arrays have only one index - 32-bit flat memory offset. Segment part of the memory address is not available. 2.3 INTEGER EXPRESSIONS ~~~~~~~~~~~~~~~~~~~~~~~ In Borland Pascal all byte sized operands of the integer arithmetic operator are converted to Integer type. In Virtual Pascal all byte and word sized operands of the arithmetic operator are converted to Longint type. 2.4 STANDARD UNIT IMPLEMENTATION DIFFERENCES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are six standard units shipped: System, Dos, Crt, Strings, WinDos and WinCrt. Source code for System unit is not available. Parameters to standard procedures/functions and function return values that in Borland Pascal have Integer or Word type are extended to be Longint. Actually, they remain to be of the Integer and Word type, but USE32 unit is used to redefine the meaning of the Word and Integer. If you do not include USE32 unit into uses clause and try to recompile your 16-bit code, you will have no portability problems for value-parameters to the standard procedures and functions that have Word or Integer arguments. For variable parameters, you will get 'Type mismatch' error, because in Virtual Pascal they are 32-bit. 2.4.1 SYSTEM UNIT ~~~~~~~~~~~~~~~~~~ Ptr standard function has only one parameter: 32-bit flat memory offset. Segment parameter is not available. 2.4.2 DOS UNIT ~~~~~~~~~~~~~~~ The following DOS specific procedures are not implemented: procedure Intr(IntNo: Byte; var Regs: Registers); procedure MsDos(var Regs: Registers); procedure GetCBreak(var Break: Boolean); procedure SetCBreak(Break: Boolean); procedure GetIntVec(IntNo: Byte; var Vector: Pointer); procedure SetIntVec(IntNo: Byte; Vector: Pointer); procedure Keep(ExitCode: Word); Procedure SwapVectors remains for compatibility but do nothing. New procedure FindClose is added. procedure FindClose(var F: SearchRec); It ends the search, initiated by FindFirst and closes the search record. FindClose should be issued whenever search record is no longer needed. Unlike DOS, OS/2 does not keep search information in the user program space (in the SearchRec). OS/2 returns only handle that identifies this information, so it should be freed, otherwise OS/2 runs out of search handles and all calls to FindFirst later on will fail. 2.4.3 WINDOS UNIT ~~~~~~~~~~~~~~~~~ The following procedures are not implemented: procedure Intr(IntNo: Byte; var Regs: TRegisters); procedure MsDos(var Regs: TRegisters); procedure GetCBreak(var Break: Boolean); procedure SetCBreak(Break: Boolean); procedure GetIntVec(IntNo: Byte; var Vector: Pointer); procedure SetIntVec(IntNo: Byte; Vector: Pointer); New procedure FindClose is added. procedure FindClose(var F: TSearchRec); It has the same purpose as FindClose procedure of the Dos unit. 2.4.4 CRT UNIT ~~~~~~~~~~~~~~ The following procedures are not implemented: procedure Sound(Hz: Word); procedure NoSound; You can use new procedure PlaySound instead. Essentially, it is the equivalent to three calls: Sound(Freq); Delay(Duration); NoSound; procedure PlaySound(Freq,Duration: Longint); 2.4.5 WINCRT AND STRING UNIT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ All procedures and functions are implemented. 2.4.6 32-BIT TURBO VISION FOR OS/2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32-bit Turbo Vision for OS/2 is available as a patch on original Borland Pascal Turbo Vision sources. Run TV4VP OS/2 command file in the \VP\SOURCE\TV directory for the details of how to apply the patch. Low level Drivers and Objects units have been rewritten completely, in other units all assembler code has been rewritten. DOS specific TEmsStream object is not implemented. TEvent record is extended to include ShiftState byte field for evKeyDown variant. Critical error handlers are not available. OS/2 handles critical errors in a proper way (unlike DOS, OS/2 does not destroy user screen). FormatStr procedure is rewritten in built-in assembler. High level units such as Menus, Dialogs, etc, remains practically unchanged. 2.5 COMPILER DIRECTIVES ~~~~~~~~~~~~~~~~~~~~~~~ All Borland Pascal compiler directives that are implemented in Virtual Pascal have the same spelling. New switch directives introduced in the Virtual Pascal have names, consisting of several letters, unlike one letter switches of the Borland Pascal (surely, it is only 26 letters). Detailed description of the Virtual Pascal compiler directives can be found in the IDE help system. Several Borland Pascal directives are not available. Virtual Pascal simply ignores them. The alternative way of entering compiler directives is available. Comment that begins with, the ampersand (&) symbol, rather than dollar sign ($), is treated as a compiler directive. It is a convenient way to specify Virtual Pascal specific directives, Borland Pascal will treat them as ordinal comments. Borland Pascal 7.0 compiler directives that have no effect in Virtual Pascal: Switch compiler directives Switch│ Meaning ══════╪═════════════════════════════════ $E │ Emulation $F │ Force FAR Calls $G │ Generate 286 Instructions $K │ Smart Callbacks $N │ Numeric Coprocessor $O │ Overlay Code Generation $W │ Windows Stack Frame $Y │ Symbol Reference Information Parameter directives Directive │ Meaning ═════════════╪══════════════════════════════ $C Attribute │Code Segment Attribute $D Text │Description $G UnitName │Group Unit Segments $O UnitName │Overlay Unit Name $R FileName │Resource File $S SegSize │Segment Size Preference 2.6 BUILT-IN ASSEMBLER ~~~~~~~~~~~~~~~~~~~~~~ Built-in assembler is extended to support 386,486 and Pentium instructions. Two new operators are introduced: Small and Large. They are used to modify memory addressing mode (Small: 16-bit, Large: 32-bit). They have the same meaning and syntax, as in other 32-bit assemblers, such as MASM or TASM. There are two pseudo instructions available ALIGN and POPARGS. ALIGN pseudo instruction accepts one constant integer operand that can have the following values: 1: No code is generated. 2: Virtual Pascal generates code to align next instruction to the word (2-byte) boundary. 4: Virtual Pascal generates code to align next instruction to the double word boundary. Code, generated by the ALIGN instruction does not change any CPU register, except EIP. POPARGS pseudo instruction accepts one constant integer operand that defines the size of the arguments that should be popped out after current subprogram returns. It has meaning only for assembler procedures and functions. This value is used for RET instruction, generated by the END statement of the assembler procedure or function. In addition to @Params and @Locals symbols, @Uses symbol is introduced. It returns total size of the registers, saved in stack by the {$USES RegList} directive. 2.7 REGISTER USAGE ~~~~~~~~~~~~~~~~~~ Unlike Borland Pascal, Virtual Pascal have different register usage convention. By default, EBX, ESI and EDI registers are used as register variables to hold intermediate values across procedure or function calls and for register Self object pointer. If procedure or function uses these registers, they are saved on entry and restored on exit. Default register usage convention is compatible with SYSCALL calling convention used by OS/2 API functions. 32-bit C/C++ compilers have the same convention too. However, you can modify default register usage convention by $Saves parameter directive, but this is not recommended. 2.7.1 EMBEDDED ASM STATEMENTS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ASM statements assume the default register convention or that one which is specified by the $Saves ($Alters) directive. For default register convention this means that EBX,ESI and EDI registers should not be changed. If you change one of them, you should inform compiler about this in the $Saves or $Alters directive. If ASM statement does not modify these registers and EAX,ECX or EDX, you may inform compiler either, so it can produce more efficient code. 2.7.2 ASSEMBLER PROCEDURES AND FUNCTIONS ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Assembler procedures and functions should conform to the current register usage convention. $USES statement can help you with this. The $USES directive is like USES directive of the macro assemblers. It specifies registers that will be pushed at the beginning of the procedure or function and popped before return. You can also use $FRAME directive to specify whether to set up stack frame or not. For small assembler routines you can disable the generation of the stack frame ($FRAME- state). In this case, access to local variables and arguments is performed via ESP register. This generates the fastest code, but may produce bugs. Access to the local variable or argument is legal only if you does not change the value of the ESP register (there are no pushes or pops). 2.8 CODE GENERATION DIFFERENCES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Nested procedures and functions use different model for accessing local variables and arguments of the enclosing procedure or function. It is based on ENTER CPU instruction, which pushes stack frame pointers of all enclosing routines at the beginning of the nested procedure or function. See Intel documentation for the details. For overflow checking compiler uses INTO CPU instruction and for range checking - BOUND. This produces faster code when range and overflow checkings are enabled. 2.9 IMPORT AND EXPORT ~~~~~~~~~~~~~~~~~~~~~ Export and import are completely different. Virtual Pascal does not support EXPORTS clause, Name and Index standard procedural directives. Virtual Pascal offers more powerful and flexible language independent approach, see section 3 for the details. 2.10 Inline statements and inline subroutines ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These Borland Pascal archaisms are not supported. Use ASM statement or assembler procedure/function instead. 3. NEW VIRTUAL PASCAL FEATURES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 3.1 CALLING CONVENTIONS ~~~~~~~~~~~~~~~~~~~~~~~ Virtual Pascal supports Pascal, 16-bit Pascal (Far16) without thunking, C and StdCall calling conventions. Calling convention defines the order of the parameters and the way of stack clean up. You can change default calling convention by specifying compiler directive as follows: Directive │ Convention │ Parameter push order │ Stack cleanup ══════════╪═══════════════╪══════════════════════╪═════════════════ $Cdecl+ │ C language │ Last to first │ Caller $Far16+ │ 16-bit Pascal │ First to last │ Called routine $StdCall+│ STDCALL │ Last to first │ Called routine Disabled │ 32-bit Pascal │ First to last │ Called routine These directives are mutually exclusive. If one directive is enabled, the other ones are disabled. Specifying any directive in the disabled state (-) enables default Pascal calling convention. For a procedure or function you can change the default calling convention by specifying Pascal, Cdecl, Far16 or StdCall standard procedure directive. Far16 Pascal calling convention is supported only for external procedures or functions. Compiler generates special code that calls external far 16-bit Pascal procedure or function via special helper routine. This helper routine has a restriction - you cannot specify more than 16 parameters to the Far16 procedure or function, if you try to specify more, compiler treats it as ordinal 32-bit Pascal. Virtual Pascal generates only 32-bit code, so Far16 directive is ignored, if it is used with non-external procedure or function. In this case calling convention would be 32-bit Pascal. It is worth to note, that you can create procedural types that use Pascal, Cdecl and StdCall calling conventions. Note, that unlike C/C++ compilers, calling convention of the Virtual Pascal does not change the case of the global identifiers and does not define whether to append leading underscore to global identifier or not. Next section describes naming convention used by Virtual Pascal. 3.2 NAMING CONVENTION ~~~~~~~~~~~~~~~~~~~~~ To satisfy the scope rules of Borland Pascal language, Virtual Pascal uses the following naming convention for public identifiers in the object file: UnitName@SymbolName UnitName@ObjectName@MethodName where UnitName is the name of the program, library or unit where symbol is defined. If program is written without heading (no program name is given), PROGRAM is assumed. SymbolName is the name of the variable, typed constant, procedure or function ObjectName is a name of the object type MethodName is a name of the object method. All names have their original case. However, for variables, typed constants, procedures and functions you can change default naming convention by specifying $OrgName+ directive. $OrgName+ puts original name of the symbol converted to upper case. Its primary purpose is to declare external OS/2 API functions, for example, see Os2Base unit source. You should also use it for interface variables, procedures and functions in your Pascal program or unit when you want to link it with modules written in other languages. 3.3 PURE INTERFACE UNITS ~~~~~~~~~~~~~~~~~~~~~~~~ Virtual Pascal stores symbol information about interface part of a unit in Virtual Pascal Interface file (.VPI). VPI files are compiler version dependent. Moreover, interface check sum sometimes depend upon compiler options used to compile unit. That is why, if you want to supply unit's object code without source, you should create pure interface unit for it. It should contain {$PureInt+} directive at the start of the unit and all interface part. If unit has an initialization part, it implementation part should be as follows: implementation begin end. otherwise only interface end. is needed. {PureInt+} directive forces the compiler to ignore undefined forward references to procedures, functions and methods, and assume that they are implemented in the original version of the unit. No object file or library is generated for pure interface unit, so when you compile it by any newer version of the compiler, it creates appropriate .VPI file for it and uses the object file or library produced from the original unit by the old version of the compiler. 3.4 DIRECT PORT ACCESS ~~~~~~~~~~~~~~~~~~~~~~ To obtain direct port access you should enable I/O privilege by specifying the following line in your OS/2 CONFIG.SYS: IOPL=YES If you use Port arrays in your Pascal program, you should either link it with DLL version of the run-time library or create linker module definition file for it with the following line included: SEGMENTS IO16 IOPL 3.5 IMPORT ~~~~~~~~~~ Virtual Pascal does not support Name and Index standard procedural directives of the Borland Pascal. External procedures or functions should be declared using only EXTERNAL standard directive, whether they are imported or not. It is totally transparent to the language. It is linker prerogative to know whether symbol is imported. Replacing static libraries by import libraries one can easily create applications that use either static or dynamic versions of the libraries. If procedure or function is imported, there are two ways to declare module name, entry name or ordinal number: - Use module definition file to specify this information. You should take into consideration naming convention of the Virtual Pascal (see 3.2 for details). - Create an import library for your dynamic link library. Then you can use its name in the $L parameter directive in a program or library which uses your DLL. Import library is created automatically by the IDE when you compile dynamic link library. It has the same name as a primary file of the library and has a .LIB extension. It is placed to the directory that is mentioned first in the Options│Directories│Library directories input box. Default import library OS2.LIB contains the import declarations of the OS/2 API functions. You need not specify it in the $L directive. 3.6 EXPORT ~~~~~~~~~~ Virtual Pascal does not support EXPORTS clause of the Borland Pascal. You can export procedure or function by specifying Export standard directive in its declaration. Note, that unlike Borland Pascal, it can be applied only to the procedure or function in the interface part of a unit, or any procedure or function in the program or library source file. As for the import, it is possible to use module definition file to export procedures, functions, variables and typed constants from the interface part of a unit or from the program or library source file. You can also export the whole interface part of the unit, including procedures, functions, object methods, variables and typed constants. You should only specify required unit name as a parameter to the $Export directive in the dynamic library source file, and that is all. See source file for DLL version of the Virtual Pascal run-time library for an example (\VP\SOURCE\RTL\VPRTL*.*). 3.7 PRESENTATION MANAGER RESOURCES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Virtual Pascal uses OS/2 resource compiler RC.EXE to compile resource script file and to bind binary resource file to the executable. Virtual Pascal IDE uses the following convention: resource script file (.RC) should be located in the directories specified in the Option│Directives│Resource directives input box or in the current directory, have the same name as primary file of the program or library, but have a .RC extension. If the IDE finds such a file, it looks for a binary resource file in the output directory (Options│Directories│Output directory input box) that has the same name but a .RES extension. If there is no binary resource file or it is older than resource script file, the IDE invokes RC to compile script file to binary resource file. Then RC is invoked to bind binary resource file to the application or dynamic link library executable. If your resource script file consists of several include files and you have modified one of them, you should 'touch' (update date) the primary script file, so the IDE may recognize that it is changed. 3.8 WRITING OS/2 DYNAMIC LINK LIBRARIES ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Dynamic link libraries generally fall into two categories - subroutine libraries and subsystems. Virtual Pascal lets you create both types of the dynamic link libraries, but subroutine libraries are commonly used. Note, that source level debugging is not available for procedures and functions located in the library source file, so it usually contains only library heading, uses clause, and initialization part (usually for subsystems). 3.8.1 SUBROUTINE LIBRARIES ~~~~~~~~~~~~~~~~~~~~~~~~~~ Subroutine libraries are the most convenient way of creating dynamic version of the units. Procedures, functions and object methods in the subroutine library are written and execute in the same way as a statically linked ones. Units, included into dynamic link library works exactly as they were linked statically. The only difference is that actual linking occurs at load time instead of linking time. OS/2 creates unique static unit data (global variables and typed constants) for each application that uses subroutine dynamic link library. Subroutine libraries need not initialization and termination code. You must use module definition file to create dynamic link library. Typically it consists of three statements: LIBRARY LibName ; specifies DLL name DATA MULTIPLE NONSHARED ; forces OS/2 to create new ; instances of data segments for ; each application that uses DLL DESCRIPTION 'Text' ; Inserts specified text into ; the library executable file 3.8.2 SUBSYSTEMS ~~~~~~~~~~~~~~~~ The term subsystem refers to a DLL that provides a set of services built around a resource. The term resource is used in the most general sense of the word, do not confuse it with Presentation Manager resource. A subsystem usually has to manage a limited resource for an effectively unlimited number of clients. That is why, subsystems have common data segment for all applications (clients) that use it. To keep track of its clients, subsystem needs to know when new clients arrive and when old clients terminate. There are two forms of subsystem initialization and termination - global and instance. A subsystem can specify either service but not both. If global initialization is specified, the initialization entry point is called only once per activation of the subsystem. When the DLL is first referenced, OS/2 allocates the subsystem's static data segments, taking their initial values from the .DLL file. OS/2 then calls the subsystem's global initialization entry point so that the module can do its one-time initialization. The second form of initialization is instance initialization. The instance initialization entry point is called in the same way as the global initialization entry point except that it is called for every new client when that client first attaches to the DLL. The same applies to the DLL termination. You must use module definition file to create subsystem's dynamic link library. Typically it consists of three statements: LIBRARY LibName <Init> <Term> ; specifies DLL name DATA SINGLE NONSHARED ; only one data segment is created DESCRIPTION 'Text' ; Inserts specified text into ; the library executable file <Init> can be either INITGLOBAL or INITINSTANCE, <Term> can be either TERMGLOBAL or TERMINSTANCE. The initialization and termination entry points are the same. They correspond to the initialization statement part of a library. To check whether initialization or termination is underway, you should use assembler function like this: { Returns True for DLL initialization } function IsInit: Boolean; assembler; {$USES None} {$FRAME-} asm cmp [ebp+0Ch],0 sete al end; It checks special parameter passed to the DLL initialization / termination by OS/2. It is 0 for initialization and 1 for termination. The usual sybsystem initialization part is the following: begin if IsInit then begin ... Initialization stuff goes here end else begin ... Termination stuff are placed here end.