Subsections

14. The OBJPAS unit

The objpas unit is meant for compatibility with Object Pascal as implemented by Delphi. The unit is loaded automatically by the Free Pascal compiler whenever the Delphi or objfpc more is entered, either through the command line switches -Sd or -Sh or with the {$MODE DELPHI} or {$MODE OBJFPC} directives.

It redefines some basic pascal types, introduces some functions for compatibility with Delphi's system unit, and introduces some methods for the management of the resource string tables.

14.1 Types

The objpas unit redefines two integer types, for compatibity with Delphi:
type
  smallint = system.integer;
  integer  = system.longint;
The resource string tables can be managed with a callback function which the user must provide: TResourceIterator.
Type
   TResourceIterator =
      Function (Name,Value : AnsiString;Hash : Longint):AnsiString;

14.2 Functions and Procedures


14.2.1 AssignFile

Declaration
Procedure AssignFile(Var f: FileType;Name: Character type);
Description
AssignFile is completely equivalent to the system unit's Assign function: It assigns Name to a function of any type (FileType can be Text or a typed or untyped File variable). Name can be a string, a single character or a PChar.

It is most likely introduced to avoid confusion between the regular Assign function and the Assign method of TPersistent in the Delphi VCL.

Errors
None.
See also
CloseFile, Assign, Reset, Rewrite, Append

Example
Program Example88;

{ Program to demonstrate the AssignFile and CloseFile functions. }

{$MODE Delphi}

Var F : text;

begin
  AssignFile(F,'textfile.txt');
  Rewrite(F);
  Writeln (F,'This is a silly example of AssignFile and CloseFile.');
  CloseFile(F);
end.


14.2.2 CloseFile

Declaration
Procedure CloseFile(Var F: FileType);
Description
CloseFile flushes and closes a file F of any file type. F can be Text or a typed or untyped File variable. After a call to CloseFile, any attempt to write to the file F will result in an error.

It is most likely introduced to avoid confusion between the regular Close function and the Close method of TForm in the Delphi VCL.

Errors
None.
See also
Close, AssignFile, Reset, Rewrite, Append

for an example, see AssignFile.


14.2.3 Freemem

Declaration
Procedure FreeMem(Var p:pointer[;Size:Longint]);
Description
FreeMem releases the memory reserved by a call to GetMem. The (optional) Size parameter is ignored, since the object pascal version of GetMem stores the amount of memory that was requested.

be sure not to release memory that was not obtained with the Getmem call in Objpas. Normally, this should not happen, since objpas changes the default memory manager to it's own memory manager.

Errors
None.
See also
Freemem, GetMem, Getmem

Example
Program Example89;

{ Program to demonstrate the FreeMem function. }
{$Mode Delphi}

Var P : Pointer;

begin
  Writeln ('Memory before : ',Memavail);
  GetMem(P,10000);
  FreeMem(P);
  Writeln ('Memory after  : ',Memavail);  
end.


14.2.4 Getmem

Declaration
Procedure Getmem(Var P:pointer;Size:Longint);
Description
GetMem reserves Size bytes of memory on the heap and returns a pointer to it in P. Size is stored at offset -4 of the result, and is used to release the memory again. P can be a typed or untyped pointer.

Be sure to release this memory with the FreeMem call defined in the objpas unit.

Errors
In case no more memory is available, and no more memory could be obtained from the system a run-time error is triggered.
See also
FreeMem, Getmem.

For an example, see FreeMem.


14.2.5 GetResourceStringCurrentValue

Declaration
Function GetResourceStringCurrentValue(TableIndex,StringIndex : Longint) : AnsiString;
Description
GetResourceStringCurrentValue returns the current value of the resourcestring in table TableIndex with index StringIndex.

The current value depends on the system of internationalization that was used, and which language is selected when the program is executed.

Errors
If either TableIndex or StringIndex are out of range, then a empty string is returned.
See also
SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example
Program Example90;

{ Program to demonstrate the GetResourceStringCurrentValue function. }
{$Mode Delphi}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;

begin
  { Print current values of all resourcestrings }
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      Writeln (I,',',J,' : ',GetResourceStringCurrentValue(I,J));
end.


14.2.6 GetResourceStringDefaultValue

Declaration
Function GetResourceStringDefaultValue(TableIndex,StringIndex : Longint) : AnsiString
Description
GetResourceStringDefaultValue returns the default value of the resourcestring in table TableIndex with index StringIndex.

The default value is the value of the string that appears in the source code of the programmer, and is compiled into the program.

Errors
If either TableIndex or StringIndex are out of range, then a empty string is returned.
Errors
See also
SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example
Program Example91;

{ Program to demonstrate the GetResourceStringDefaultValue function. }
{$Mode Delphi}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;

begin
  { Print default values of all resourcestrings }
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      Writeln (I,',',J,' : ',GetResourceStringDefaultValue(I,J));
end.


14.2.7 GetResourceStringHash

Declaration
Function GetResourceStringHash(TableIndex,StringIndex : Longint) : Longint;
Description
GetResourceStringHash returns the hash value associated with the resource string in table TableIndex, with index StringIndex.

The hash value is calculated from the default value of the resource string in a manner that gives the same result as the GNU gettext mechanism. It is stored in the resourcestring tables, so retrieval is faster than actually calculating the hash for each string.

Errors
If either TableIndex or StringIndex is zero, 0 is returned.
See also
Hash SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

For an example, see Hash.


14.2.8 GetResourceStringName

Declaration
Function GetResourceStringName(TableIndex,StringIndex : Longint) : Ansistring;
Description
GetResourceStringName returns the name of the resourcestring in table TableIndex with index StringIndex. The name of the string is always the unit name in which the string was declared, followed by a period and the name of the constant, all in lowercase.

If a unit MyUnit declares a resourcestring MyTitle then the name returned will be myunit.mytitle. A resourcestring in the program file will have the name of the program prepended.

The name returned by this function is also the name that is stored in the resourcestring file generated by the compiler.

Strictly speaking, this information isn't necessary for the functioning of the program, it is provided only as a means to easier translation of strings.

Errors
If either TableIndex or StringIndex is zero, an empty string is returned.
See also
SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example
Program Example92;

{ Program to demonstrate the GetResourceStringName function. }
{$Mode Delphi}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;

begin
  { Print names of all resourcestrings }
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      Writeln (I,',',J,' : ',GetResourceStringName(I,J));
end.


14.2.9 Hash

Declaration
Function Hash(S : AnsiString) : longint;
Description
Hash calculates the hash value of the string S in a manner that is compatible with the GNU gettext hash value for the string. It is the same value that is stored in the Resource string tables, and which can be retrieved with the GetResourceStringHash function call.
Errors
None. In case the calculated hash value should be 0, the returned result will be -1.
See also
GetResourceStringHash,

Example
Program Example93;

{ Program to demonstrate the Hash function. }
{$Mode Delphi}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;

begin
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      If Hash(GetResourceStringDefaultValue(I,J))
        <>GetResourceStringHash(I,J) then
        Writeln ('Hash mismatch at ',I,',',J)
      else
        Writeln ('Hash (',I,',',J,') matches.');
end.


14.2.10 Paramstr

Declaration
Function ParamStr(Param : Integer) : Ansistring;
Description
ParamStr returns the Param-th command-line parameter as an AnsiString. The system unit Paramstr function limits the result to 255 characters.

The zeroeth command-line parameter contains the path of the executable, except on LINUX, where it is the command as typed on the command-line.

Errors
In case Param is an invalid value, an empty string is returned.
See also
Paramstr

For an example, see Paramstr.


14.2.11 ResetResourceTables

Declaration
Procedure ResetResourceTables;
Description
ResetResourceTables resets all resource strings to their default (i.e. as in the source code) values.

Normally, this should never be called from a user's program. It is called in the initialization code of the objpas unit. However, if the resourcetables get messed up for some reason, this procedure will fix them again.

Errors
None.
See also
SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount


14.2.12 ResourceStringCount

Declaration
Function ResourceStringCount(TableIndex : longint) : longint;
Description
ResourceStringCount returns the number of resourcestrings in the table with index TableIndex. The strings in a particular table are numbered from 0 to ResourceStringCount-1, i.e. they're zero based.
Errors
If an invalid TableIndex is given, -1 is returned.
See also
SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount,

For an example, see GetResourceStringDefaultValue


14.2.13 ResourceStringTableCount

Declaration
Function ResourceStringTableCount : Longint;
Description
ResourceStringTableCount returns the number of resource string tables; this may be zero if no resource strings are used in a program.

The tables are numbered from 0 to ResourceStringTableCount-1, i.e. they're zero based.

Errors
See also
SetResourceStrings, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringCount

For an example, see GetResourceStringDefaultValue


14.2.14 SetResourceStrings

Declaration
TResourceIterator = Function (Name,Value : AnsiString;Hash : Longint):AnsiString;

Procedure SetResourceStrings (SetFunction : TResourceIterator);

Description
SetResourceStrings calls SetFunction for all resourcestrings in the resourcestring tables and sets the resourcestring's current value to the value returned by SetFunction.

The Name,Value and Hash parameters passed to the iterator function are the values stored in the tables.

Errors
None.
See also
GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example
Program Example95;

{ Program to demonstrate the SetResourceStrings function. }
{$Mode objfpc}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;
    S : AnsiString;
    
Function Translate (Name,Value : AnsiString; Hash : longint): AnsiString;    
 
begin
  Writeln ('Translate (',Name,') => ',Value);
  Write   ('->');
  Readln  (Result); 
end; 
    
begin
  SetResourceStrings(@Translate);  
  Writeln ('Translated strings : ');    
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      begin
      Writeln (GetResourceStringDefaultValue(I,J));
      Writeln ('Translates to : ');
      Writeln (GetResourceStringCurrentValue(I,J));
      end;
end.


14.2.15 SetResourceStringValue

Declaration
Function SetResourceStringValue(TableIndex,StringIndex : longint; Value : Ansistring) : Boolean;
Description
SetResourceStringValue assigns Value to the resource string in table TableIndex with index StringIndex.
Errors
See also
SetResourceStrings, GetResourceStringCurrentValue, GetResourceStringDefaultValue, GetResourceStringHash, GetResourceStringName, ResourceStringTableCount, ResourceStringCount

Example
Program Example94;

{ Program to demonstrate the SetResourceStringValue function. }
{$Mode Delphi}

ResourceString

  First  = 'First string';
  Second = 'Second String';

Var I,J : Longint;
    S : AnsiString;
    
begin
  { Print current values of all resourcestrings }
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      begin
      Writeln ('Translate => ',GetResourceStringDefaultValue(I,J));
      Write   ('->');
      Readln(S); 
      SetResourceStringValue(I,J,S); 
      end;
  Writeln ('Translated strings : ');    
  For I:=0 to ResourceStringTableCount-1 do
    For J:=0 to ResourceStringCount(i)-1 do
      begin
      Writeln (GetResourceStringDefaultValue(I,J));
      Writeln ('Translates to : ');
      Writeln (GetResourceStringCurrentValue(I,J));
      end;
end.



root
2000-12-20