Support Statement: Using a gmAPI executable with gmStudio
The gmAPI Paradigm
The paradigm for using a gmAPI executable with gmStudio is a bit different than using gmStudio with gmBasic. The difference begins with setting the TScript field on a gmProj Task. To use gmBasic, the TScript field specifies and gmPL translation script template. To use a gmAPI executable, the TScript field is set to the path of a gmAPI.exe file.
- gmBasic: gmStudio prepares an actual translation script (JobID.xml) for the task being processed by detokenizing %placeholders% and merging ScriptRules with the template translation script file specified by the Tscript field.
gmStudio then spawns gmBasic.exe as a separate process passing the actual translation script as a command line argument. gmBasic.exe executes the actual translation script. - gmAPI: gmStudio prepares a task information file (JobID.xml) based on the attributes of the task being processed. gmStudio spawns your gmAPI Exe (e.g. Upgrade.exe) passing the task information file as a command line argument. Upgrade.exe uses the TaskInfo, ScriptRules , and gmslLibrary APIs as needed to invoke gmBasic services.
The use of ScriptRules file(s) are optional in the gmPL approach because a developer can insert custom XML commands (i.e. Select, Registry, Fix, Refactor) into the template translation script manually. However, since there are no translation scripts with the gmAPI approach, ScriptRules are typically required to integrate XML.
The gmslAPI.dll integrates gmAPI, TaskInfo, and ScriptRules APIs into one assembly. The assembly depends on the Service Command Model Operations DLL (SCMoperations.dll) for implementation of gmBasic services. SCMoperations.dll is a Win32 DLL requiring you build your gmAPI executable with Platform=x86.
gmAPI is built on Managed-Native integration. The implementation of gmBasic services that power gmAPI services were developed to work in the gmBasic.exe console application and some behavior may be non-intuitive. We are working on improvements to this API to make it more a natural fit for custom managed EXEs.
See also
gmAPI reference and samples are here: gmAPIIntroduction