gmSCProcessServicesClass

Owned by Mark Juras
Last updated: Jul 25, 2018Version comment

The ProcessServices Service Class

The service class ProcessServices implements the gmNI process services. A ProcessService is a method whose implementation is not implemented in the same build-component as its reference.

The field ProcessServices_AuthorCode

Prototype


typedef int  (*tServiceAuthorCode)(int codeStart,int codeEnd,int codeDial,char* buffer);
extern tServiceAuthorCode ProcessServices_AuthorCode;
The ProcessServices_AuthorCode field is the handle for the method within the tool that authors operation code. It must be initialized with the tool code.

The field ProcessServices_Engine

Prototype


typedef int  (*tServiceEngine)(UBYTE* code,int nCode,void* vValues);
extern tServiceEngine ProcessServices_Engine;
The ProcessServices_Engine field is the handle for the method within the tool that executes operation code. It must be initialized with the tool code.

The field ProcessServices_hServices

Prototype


typedef void*  (*HandleService)();
extern HandleService* ProcessServices_hServices;
The ProcessServices_hServices field is the handle to the vector of handles to the handle returning methods implemented in the tool but used by the runtime code as defined in the Services.h header file. It must be initialized with the tool code.

The field ProcessServices_iServices

Prototype


typedef int    (*IntegerService)();
extern IntegerService* ProcessServices_iServices;
The ProcessServices_iServices field is the handle to the vector of handles to the integer returning methods implemented in the tool but used by the runtime code as defined in the Services.h header file. It must be initialized with the tool code.

The field ProcessServices_ivServices

Prototype


typedef int*   (*IVectorService)();
extern IVectorService* ProcessServices_ivServices;
The ProcessServices_ivServices field is the handle to the vector of handles to the integer vector returning methods implemented in the tool but used by the runtime code as defined in the Services.h header file. It must be initialized within the tool code.

The field ProcessServices_Quantity

Prototype


typedef int  (*tServiceQuantity)(UBYTE* code,int icode,int* qeType,int* qeAddr,int* qeStack,
                                 void* expr,int subRoot);
extern tServiceQuantity ProcessServices_Quantity;
The ProcessServices_Quantity field is the handle for the method within the tool that scans operation code to determine the types of quantity expressions present. It must be initialized within the tool code.

The field ProcessServices_ReadFactor

Prototype


typedef int  (*tServiceReadFactor)(int* Parents,void* xQuant,int exp,int isSet);
extern tServiceReadFactor ProcessServices_ReadFactor;
The ProcessServices_ReadFactor field is the handle for the method within the tool that compiles factor references within source code expressions. It must be initialized with the tool code.

The field ProcessServices_sServices

Prototype


typedef char*  (*StringService)();
extern StringService* ProcessServices_sServices;
The ProcessServices_sServices field is the handle to the vector of handles to the string returning methods implemented in the tool but used by the runtime code as defined in the Services.h header file. It must be initialized within the tool code.

The field ProcessServices_vServices

Prototype


typedef void   (*VoidService)();
VoidService* ProcessServices_vServices;
The ProcessServices_vServices field is the handle to the vector of handles to the void methods implemented in the tool but used by the runtime code as defined in the Services.h header file. It must be initialized with the tool code.

The field ProcessServices_WriteCode

Prototype


typedef void (*tServiceWriteCode)(UBYTE* code,int iRoot,int iStart,int iEnd,int showQe,
                                  void* textStream,int item);
extern tServiceWriteCode ProcessServices_WriteCode;
The ProcessServices_WriteCode field is the handle for the method within the tool that writes operation code in its gmIL form. It must be initialized with the tool code.

The method ProcessServices_AddLibrary

Prototype


int ProcessServices_AddLibrary(int libRoot, char* dllName, char* codeId);
The ProcessServices_AddLibrary method adds a dynamic link library, possibly linked to a library description file that is being refactored, to the list of runtime codes to be called. Its parameters are:

Parameter Description
libRoot Specifies the root offset or the library that is being refactored by the runtime code. It may be zero, if the runtime code does not pertain to a particular library.
dllName Contains the name of a dll file that should be loaded and should remain loaded for the remainder of the current execution. Up to 64 Dlls may be loaded at the same time. The method uses the standard search order to locate the actual file.
codeId Contains a string which is used to trigger a set of generic user migration code events within the analyser. It can be NULL.

If all goes well, the method returns a zero; else it returns a nonzero error code as follows:

Code Meaning
1 The file could not be found in any of the four search locations.
2 The file was found but it could not be opened as a runtime dll.
3 The runtime Dll did not have an IntializeServices method.


The method ProcessServices_AuthorClass

Prototype


int ProcessServices_AuthorClass(int iStart,int iEnd,char* service,char* parentName);
The ProcessServices_AuthorClass method is used by the author immediately before it writes the declaration of a class file. If present, it supplies an optional name for the parent of the class and for a service name to be authored as part of a System.Runtime.InteropServices.ProgId declaration. The method scans all loaded runtime codes in load order for an AuthorClass handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
iStart Specifies the starting offset in the global code block of the class declaration code.
iEnd Specifies the ending offset in the global code block of the class declaration code.
service Receives the name of the service in null-terminated form. Its length may be zero.
parentName Receives the name of the parent class in null-terminated form. Its length may be zero.

The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_AuthorClassFile

Prototype


int ProcessServices_AuthorClassFile(int classRoot,int support);
The ProcessServices_AuthorClassFile method is used by the author of VB6 class files to completely override the authoring of a class file. The author of ASP page slices uses it to author special interface or implementation logic. The method scans all loaded runtime codes in load order for an AuthorClassFile handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
classRoot Specifies the root offset of the class or page slice being authored.
support Specifies support information. For class files it is the root offset of the parent project file. For page slices it is AUTARG_ININTERFACE or AUTARG_IMPLEMENTS depending upon what is needed.

The method returns a one if a handler was found that returned a one -- i.e., authored something; else it returns zero.

The method ProcessServices_AuthorDeclaration

Prototype


int ProcessServices_AuthorDeclaration(int target);
The ProcessServices_AuthorDeclaration method is used to override the authoring of some component by the author. It is only called if the migRuntime attribute of that component has a bit set that corresponds to one of the libraries. This setting must have been done by an earlier service method call. The method scans those loaded runtime codes in load order whose bit is set for an AuthorDeclaration handler. Each is called until a nonzero return value is obtained. Its parameter is:

Parameter Description
target Specifies the root offset of the component whose declaration is to be authored.

The method returns a one if a handler was found that returned a one -- i.e., authored the declaration; else it returns zero.

The method ProcessServices_AuthorLibraryStub

Prototype


int ProcessServices_AuthorLibraryStub(int target,int context);
The ProcessServices_AuthorLibraryStub method is used by the author of library wrappers to author any additional needed components being referenced that are external to the code project itself. The method scans all loaded runtime codes in load order for an AuthorLibraryStub handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
target Specifies the root offset of the library for which additional wrapper declarations might be needed.
context Specifies the type of stubs being authored. A value of zero indicates normal stubs while a value of one indicates extension method stubs.

The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_AuthorProjectFile

Prototype


int ProcessServices_AuthorProjectFile(int projectRoot,int context);
The ProcessServices_AuthorProjectFile method is used by the author to possibly override or to modify the authoring of the project control or assembly file for a VB6 translation. The method scans all loaded runtime codes in load order for a AuthorProjectFile handler. Each is called until a nonzero return value is obtained. Its parameters are as follows:

Parameter Description
projectRoot specifies the root offset of the VB6 project file for which the control file might be needed.
context Specifies the context of the call:

Code Meaning
0 The tool is about to author the assembly file. A return value of one here will override this entirely.
1 The tool is starting to author the library descriptions. A return value of one here will cause the tool to do the next call.
2 The tool has completed authoring the library descriptions.


The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_AuthorReference

Prototype


int ProcessServices_AuthorReference(int projRoot);
The ProcessServices_AuthorReference method is used by the author while it is writing the project file immediately before writing the list of external references needed by project. These typically look as follows 


 <Reference Include="ADODB">
    <Name>ADODB</Name>
    <HintPath>\deploy\externs\Interop.ADODB.dll</HintPath>
  </Reference>
The information for this list comes from the name and location attributes of the library commands in the referenced IDFs. The purpose of this method is to give user the opportunity to change how the reference is to be written. Since the method is called only once, using it typically requires two things -- first, declare the location of the reference as DoNotDeclare and second, author the desired reference within a AuthorReference method in a library. The method scans all loaded runtime codes in load order for AuthorReference handlers. Each is called. Its parameter is:

Parameter Description
projRoot Contains the root offset of the project whose references are being authored. It is typically used within this handler to detect the presence of other references which effect how the current one is to be authored.

The method returns a nonzero value if any of the handlers called returned a nonzero value; else it returns zero.

The method ProcessServices_BeginProperty

Prototype


int ProcessServices_BeginProperty(char* action,int ctlType,int ctlRoot);
The ProcessServices_BeginProperty method is called by the property bag compiler when it encounters a BeginProperty statement. It determines which, if any, runtime code is available to process a control of a specified type. If so the BeginProperty handler is called if available. Its parameters are:

Parameter Description
action Receives a description of the action to be performed: Ignore, Skip, or Begin.
ctlType Specifies the root offset of the control type information.
ctlRoot Specifies the root offset of the actual control whose properties are being compiled.

If a called handler specifies how the BeginProprty is to be dealt with via the action parameter, then this method returns a one; else if returns a zero.

The method ProcessServices_CallLateBinding

Prototype


int ProcessServices_CallLateBinding(char* className,char* methodName);
The ProcessServices_CallLateBinding method is called by the engine when it encounters a CBN, CLM operation sequence specifying that an unrecognized method of a class instance be called. The event identifiers associated with the currently loaded runtime codes are searched for an event identifier that matches the class instance name. If found and if that runtime code has a CallLateBinding handler, it is called using the method name. Its parameters are:

Parameter Description
className Contains the identifier of the class instance.
methodName Contains the method name.

If a called handler executes the specified method then a nonzero value is returned; else a zero is returned.

The method ProcessServices_CodeEvent

Prototype


int ProcessServices_CodeEvent(int codeScan,int target,int hostSub,int secStart,int callStart,
                              int iRefer,int* delta);
The ProcessServices_CodeEvent method is called by the analyser first during the initialization phase and second during the code review phase for each code block in the current scope of the analyser. It is triggered by references in the code to subcomponents that have a migUserCode value attributed to them. This is normally done with the Migrate command within a Refactor specification. The following are some examples of this for scrrun.dll. 


<Refactor id="[scrrun.dll]" dllName="ScrrunMigration.dll" event="scrrun" >

<Migrate id="IFileSystem.Drives" migUsercode="scrrun"/>
<Migrate id="ITextStream.AtEndOfStream" refType="Method" nPram="1"
          cshPattern="(%1d.Peek() == -1)"
          vbnPattern="(%1d.Peek() = -1)"
          migUsercode="scrrun.read"/>
<Migrate id="ITextStream.WriteBlankLines" migUsercode="scrrun.write"/>
This method compares the first token of the code event string against the event identifiers of the currently loaded runtime codes. If a matching event string is found and if that runtime code has a CodeEvent handler registered, then this method executes that handler and returns its return value. Its parameters are:

Parameter Description
codeScan Specifies which pass within the analyser has detected the code reference -- Initial or CodeReview.
target Specifies the root offset of the subcomponent that contained the migUsercode that triggered this method.
hostSub Specifies the root offsets of the user subprogram containing reference to the triggering subcomponent.
secStart Specifies the start of the code section within the global code block containing the reference. This is either zero or the code offset immediately following the operation that triggered this method.
callStart specifies the code start of statement with reference. Thus, it is the offset of the start of the reference to the subcomponent.
iRefer Specifies the offset of the actual referencing opcode.
delta returns a one if the code block was changed; else it returns a zero.

The method returns the offset of the next code to be examined by the overall migration control service. If the code is not restructured then it is merely the offset of the first instruction beyond the reference instruction. If the code is restructured then it is the offset of the start of the next code section to be analysed. If there is no handler found to process the reference then a zero is returned.

The method ProcessServices_CompileScript

Prototype


int ProcessServices_CompileScript(int* Parents,int pass);
The ProcessServices_CompileScript method is used by the ASP pass one compiler when it encounters JavaScript. This method scans all loaded runtime codes in load order for a CompileScript handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
Parents Contains the number of parents controlling the current compilation and the root offsets of those parents.
pass Specifies the number of the compiler pass that encountered the script.

The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_EditAspSource

Prototype


int ProcessServices_EditAspSource(int fileRoot);
The ProcessServices_EditAspSource method is used by the source file loader immediately after it has loaded a VB6 or ASP source file into an internal text buffer where it could be edited prior to its compilation. This method scans all loaded runtime codes in load order for EditAspSource handlers. Each is called. Its parameter is:

Parameter Description
fileRoot Contains the root offset of the code file whose source has just been loaded.

The method returns a nonzero value if any of the handlers called returned a nonzero value; else it returns zero.

The method ProcessServices_EditProgId

Prototype


int ProcessServices_EditProgId(char* command,int context);
The ProcessServices_EditProgId method is used by the compiler of CreateObject statements to give the runtime system the opportunity to modify the ProgId to be compatible with the tool environment. A ProgId is the identifier of a program class as it appears in CreateObject statements, New requests, and As attributes. This method is used to edit ProgIds to make them usable in the indicated context. This method scans all loaded runtime codes in load order for a EditProgId handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
command Contains the content of the command the contains a ProgId.
context Specifies the context in which the command occurs. As of now its only value is constant PROGID_CREATEOBJECT.

The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_EditStatement

Prototype


int ProcessServices_EditStatement(char* Statement,int context);
The ProcessServices_EditStatement method is used by the compiler as it reads source records to be compiled. This method gives the user the opportunity to modify that record on the fly before it is parsed. This method scans all loaded runtime codes in load order for an EditStatement handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
Statement Contains the actual source statement within the statement buffer that will be parsed by the compiler.
context Specifies the type of statement being read:

Value Meaning
2 A continuation record within an ASP file is being read
1 An initial record within an ASP file is being read
0 A VB6 or gmSL source statement is being read
-1 A source statement is being read during pass 1 of the compiler


The method returns a one if a handler was found that returned a one; else it returns zero.

The method ProcessServices_EditTranslation

Prototype


int ProcessServices_EditTranslation(int target);
The ProcessServices_EditTranslation method is called immediately before the author writes the target language stream to the output file. The method scans the runtime codes currently loaded and calls their EditTranslation event handler, if there is one. Its parameter is:

Parameter Description
target Specifies the root offset of the component whose target language stream is to be written.

The method returns a non-zero value, if any of the called handlers returns a nonzero value; else it returns zero.

The method ProcessServices_ExecuteCommand

Prototype


int ProcessServices_ExecuteCommand(char* command,int nCommand);
The ProcessServices_ExecuteCommand method executes statements at the primary level of a command script. It is called whenever the tool encounters a script command at that level that it does not recognize. This method executes any defined ExecuteCommand event handlers in each loaded runtime code in the order that those codes were loaded. Its parameters are:

Parameter Description
command Contains the actual statement as entered in the script. Handlers called that process any substatements are expected to use this parameter to contain them.
nCommand Specifies the size of the command buffer, not the length of the statement it Contains.

If one of the called handlers returns a non-zero value, then the tool assumes that the script command was processed by that code, ends its search, and returns the non-zero value. If no runtime code indicates that it has processed the command, then the method returns a zero.

The method ProcessServices_FinishAnalyser

Prototype


int ProcessServices_FinishAnalyser(void);
The ProcessServices_FinishAnalyser method is called when the underlying code analysis has been completed, before it is passed to the author for surface-form formation. The method has no parameters. It scans the runtime codes currently loaded and calls their FinishAnalyser handler, if there is one.

The method returns a non-zero value, if any of the called handlers returns a nonzero value; else it returns zero.

The method ProcessServices_GetLateBinding

Prototype


int ProcessServices_GetLateBinding(char* className,char* propName, int target, char* buffer);
The ProcessServices_GetLateBinding method is called by the interface author when it needs the "InterfaceAttribute" name or the "DeclareInterface" name for the interface. The event identifiers associated with the currently loaded runtime codes are searched for an event identifier that matches the class instance name. If found and if that runtime code has a GetSpecialName handler, it is called using a property name. Its parameters are:

Parameter Description
className Contains the identifier of the class instance.
propName Contains the name of the property whose special name is needed.
target Contains the root offset of the class whose interface is being authored.
buffer Receives the special name to be used.

If a called handler supplies the specified name then the length of that name as stored in the buffer parameter is returned; else a zero is returned.

The method ProcessServices_GetSpecialName

Prototype


int ProcessServices_GetSpecialName(int target,char* propName, char* buffer);
The ProcessServices_GetSpecialName method is called by the declarations author when it needs an "InterfaceName" name for some target component. It is also the implementation of the gmSL method Runtime.GetSpecialName(int target,string propName). This method attempts to call a GetSpecialName handler only if the migRuntime attribute of the target component has bits set that corresponds to one of the loaded runtime codes. It scans those loaded runtime codes in load order whose bit is set for an GetSpecialName handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
target Specifies the root offset of the component for whom a special name is needed.
propName Contains the name of the property of the component whose special name is needed.
buffer Receives the special name to be used.

If a called handler supplies the specified name then the length of that name as stored in the buffer parameter is returned; else a zero is returned.

The method ProcessServices_LoadIdf

Prototype


int ProcessServices_LoadIdf(int target);
The ProcessServices_LoadIdf method is called when a interface description file is loaded. It is used to modify the attributes of the interface components so that they can be migrated. Its parameter is:

Parameter Description
target Specifies the root offset of the library whose description has been loaded.

The method returns a one if a handler was found that returned a one -- i.e., modified the content of the description; else it returns zero.

The method ProcessServices_LoadLibrary

Prototype


int ProcessServices_LoadLibrary(int libRoot, char* refpath, char* codeId);
The ProcessServices_LoadLibrary method uses the operating system to load a specified the runtime code or Dll. Its parameters are:

Parameter Description
libRoot Specifies the offset of the library whose components are to trigger the events.
refPath Contains the name of the file for the runtime code.
codeId Contains the trigger event identifier.

If all goes well, the method returns a zero; else it returns a nonzero error code as follows:

Code Meaning
2 The file was found but it could not be opened as a runtime dll.
3 The runtime Dll did not have an InitializeServices method.


The method ProcessServices_LoadRuntime

Prototype


void ProcessServices_LoadRuntime(char* dllname,char* event,char* filename);
The ProcessServices_LoadRuntime method loads a runtime Dll into the current execution space as a runtime code. This Dll may well be intermingled with Dlls loaded via the selected runtime environment and Dlls loaded via refactoring operations. There are a maximum of 64 Dlls that may be loaded. Each DLL exports certain methods, event handlers, that are then looked for by the execution logic when certain things happen or when certain points in the processing are reached. Its parameters are as follows:

Parameter Description
dllname optionally specifies a simple local file name of the runtime Dll to be loaded. It is looked for using the standard search order. That order is target location, local location, system location, and language location.
event optionally specifies the identifier of a CodeEvent event handler if the DLL being loaded implements one. This event is triggered by references in the code to subcomponents that have a migUserCode value attributed to them.
filename optionally specifies the full pathname of the runtime Dll to be loaded. It is used only if the dllname parameter is NULL.

This method itself has no return value.

The method ProcessServices_RunSupportMethod

Prototype


int ProcessServices_RunSupportMethod(int target,char* methodName);
The ProcessServices_RunSupportMethod method is called by the author when it is declaring a class and checks for the need to author a special method such as dispose. It is only called if the migRuntime attribute of that class has a bit set that corresponds to one of the runtime codes. This method scans those loaded runtime codes in load order whose bit is set for an CallLateBinding handler. Each is called until a nonzero return value is obtained. Its parameters are:

Parameter Description
target Specifies the root offset of the class whose declaration is to be authored.
methodName Contains the name of the support method to be authored.

The method returns a one if a handler was found that returned a one -- i.e., authored the support method; else it returns zero.

The method ProcessServices_StartAnalyser

Prototype


int ProcessServices_StartAnalyser(void);
The ProcessServices_StartAnalyser method is called by the analyser first before it performs any other operations. Its purpose is to allow the user to do any initializations that might be needed later. This handler is usually used to support the transform handler which is triggered by markers in the library components information vectors that are placed there by this handler. The method has no parameters.

This method returns a non-zero value if any of the called handlers made any changes in library component information vectors; else it returns zero.

The method ProcessServices_StartPass2

Prototype


int ProcessServices_StartPass2(int target);
The ProcessServices_StartPass2 method is called immediately before the compiler starts its second pass while compiling a project code or a pageslice. The first pass of the compiler has been completed; therefore, the global symbols table is present. No code has been generated and no local variables have been stored in the symbol table. The method scans the runtime codes currently loaded and calls their StartPass2 event handler if there is one. All StartPass2 handlers are called. Its parameter is:

Parameter Description
target Specifies the root offset of the project being compiled or zero if all projects are being compiled.

The method returns a non-zero value, if any of the called handlers returns a nonzero value; else it returns zero.

The method ProcessServices_Transform

Prototype


int ProcessServices_Transform(int subRoot,int target,int iRefer,int* qeStack);
The ProcessServices_Transform method is called by the analyser during its final scan of the code. It is triggered by references to components in the code that have a nonzero marker in the migTransform member of their information vector. These markers are typically entered via a call to the StartAnalyser event. Transformation is controlled entirely by the runtime code. It does not expect or require any entries in the IDFs for the library components being migrated. Its parameters are:

Parameter Description
subRoot Specifies the root address of the user subprogram containing the reference to the target subcomponent.
target Specifies the root address of the component that contained the migTransform entry that triggered this method.
iRefer Specifies offset in the global code block with the reference -- i.e the offset of actual reference opcode for the target component.
qeStack Contains an integer vector that is maintained by the utilities that do the code scanning. It contains the current number of queue entries that would be in the stack if the sequence were being executed up to the target reference. In addition it contains the offset of the start of each queue entry. This vector is needed because many code groups refer to variable codeblocks that precede the actual target reference in the code. For example in the case of a property setter both the rightSide codeblock and hostObject codeblock precede the actual reference to the target property.

This method returns the offset of the next code to be examined by the overall migration control process. If the code is not restructured then it is merely the offset of the first instruction beyond the reference instruction. If the code is restructured then it is the offset of the start of the next code section to be analysed. If there is no handler found to process the reference then a zero is returned.
Table of Contents