GHSCOM MANUAL

 

Working with GHSCOM

After GHSCOM is properly installed on the host computer, two additional files, GHSCORE.DLL and GHSCOM.DLL, reside in the GHS program directory. The one that must be identified within the host program is GHSCOM and the name of its interface is "Application". For example, to link to GHSCOM in a VBA program and create an Application object, the statements could be,

  dim ghsObj as GHS.Application
  set ghsObj = New GHS.Application
Or if using a scripting language, an Application object would be created as follows,
  dim ghsObj
  set ghsObj = CreateObject("GHSCOM.Application")
Note: CreateObject("GHSCOM.Application") should only be used in scripting languages as this is much slower than the "dim xxx As GHS.Application" method. VB and VBA support both methods. The first method is the only way VB Script can create the object.

An example of linking to GHSCOM in the C++ language is provided in the sample file named CallFromC.cpp that is included with the GHSCOM distribution.

When linked to the host program, the GHSCOM Application interface provides three functions that allow sending commands to GHS and querying for variable values. These functions are described below.


Command

This function provides for execution of a GHS command string. Only one command should be given in this string since the "|" command separator is not supported here as it is in the standard GHS command interface.

VB syntax:

Command(commandString As String)

C/C++ syntax:

HRESULT Command(BSTR commandString)


GetVariableString

This function gets the current contents of a GHS variable as a string.

VB syntax:

GetVariableString(variableName As String) As String

C/C++ syntax:

HRESULT GetVariableString(BSTR variableName, BSTR* contents)



GetVariableValue

Similar to GetVariableString, this function gets the contents of a GHS variable as a real numeric value. If the variable is actually a string-type and cannot be converted to a number, the returned value is zero.

VB syntax:

GetVariableValue(variableName As String) As Single

C/C++ syntax:

HRESULT GetVariableValue(BSTR variableName, float* value)



Error Handling

GHSCOM supports the ISupportErrorInfo COM interface. This means that information about errors is available through the VBA "Err" object or via GetErrorInfo in C++. For example, in VB,
  on error resume next
  ghsObj.Command("RA")
  if Err.Number<>0 then
    print Err.Description
    Err.Clear
  end if



Limitations

As mentioned above, a subset of the GHS Main Program commands are available through GHSCOM. There is no access to MC, SE, LE, CG or any module accessed throught the ENTER command.

It should be noted that the GHSCOM interface can access only one instance of GHSCOM at any time. No matter how many IApplication objects it creates, they all refer to the same instance of GHS.




Examples

Files for two examples are provided to demonstrate how to use GHSCOM.

Spreadsheet.xls

This is a spreadsheet sample showing how to call GHSCOM from inside Excel using VBA. It allows you to type values in cells and have other cells updated with appropriate GHS- calculated values.

Clicking on the toolbar button or selecting the menu item,

Tools/Macro/Visual Basic Editor

will display the Visual Basic Editor. This is where you enter VBA code for working with GHSCOM. If you are new to VBA, there are good tutorials on the web and in books.

In order to use GHSCOM in Excel, you need to make sure the spreadsheet is referencing the GHSCOM library. When inside the Visual Basic Editor select the menu item,

Tools/References

This brings up the References dialog box. Make sure the GHS Type Library is checked. Now you are ready to code GHS functionality into your spreadsheet.

Create a variable of type GHS.Application and use this object to call GHS functions. The source code should be self-explanatory.


CallFromC

This example demonstrates how to get access to GHSCOM from C++ code. The sample is provided as a Visual C++ 6.0 project. The source code is contained in CallFromC.cpp and should be readable from any text editor.

The header files for declaring the GHSCOM interfaces are provided. You should follow the standard approach to working with COM objects in C++. This can be a little tricky, so you should have some knowledge on this topic before coding for GHSCOM (especially understanding the Iunknown interface).




GHSCORE.DLL

GHSCOM makes use of GHSCORE.DLL which is a standard Dynamic Link Library of core GHS functions. It is more convenient and much easier to acccess CHSCORE by linking to the GHSCOM interface. Using GHSCORE directly is not generally recommended.

Most of the information below only applies when using GHSCORE directly; however the list of commands at the end of this section also applies to GHSCOM.

The following named functions are exposed within GHSCORE.DLL:

"Command" - executes standard GHS command line.
Parameters:
1. commandline - null-terminated command line (string passed by value)

"GetError" - gets message string for last failed Command.
Parameters:
1. message - null-terminated error message (string passed by reference)
2. maxsize - maximum message size (unsigned integer passed by value)

"GetStringVar" - gets string contents of named variable, or empty on failure.
Parameters:
1. name - null-terminated variable name (string passed by value)
2. contents - null-terminated string contents (string passed by reference)
3. maxsize - maximum contents size (unsigned integer passed by value)

"GetRealVar" - gets real contents of named variable, or zero on failure.
Parameters:
1. name - null-terminated variable name (string passed by value)
2. contents - real contents of variable (real passed by reference)

All of these functions return an optional unsigned integer status value. The following return values have been defined:
  0 = SUCCESS
  1 = FAIL      (failed command or undefined GetRealVar value)
  2 = UNKNOWN   (unknown command or variable name)
  3 = DEAD      (inactive GHSCORE following a fatal error)
GHSCORE.DLL includes all the core GHS commands, but excludes graphic user interface commands (such as SCREEN), general-purpose functions present in any high-level programming language (such as IF and CHDIR), hooks to external programs (such as SE), comments ("`"), and multi-command lines ("|").


The following is an alphabetical list of all GHS commands recognized by the "Command" function in GHSCORE.DLL:
 ADD          DELETE       GROUPS           MAXVCG       SET          TMMT
 ANGLES       DEPTH        HEEL             NOTE         SMOD         TRIM
 AXIS         DISK         HEIGHT           PAGE         SOLVE        TYPE
 BOOM         DIVISIONS    HMMT             PARTS        SPGR         UNITS
 CC           DRAFT        HS               PERM         STABILITY    VARIABLE
 CHANGE       FIX          LBP              PROJECT      STATUS       VARY
 CLEAR        FLDPT        LCG              RAH          SUBTITLE     VCG
 COMMENTS     FSMMT        LIMITS           READ         TANKS        WATER
 COMPONENT    FSMFLOOR     LOAD (not EDIT)  REFPT        TC           WAVE
 CONTENTS     GHS          LS               ROLL         TCG          WEIGHT
 CRTP         GMTMMT       LSLIMIT          RUN          TITLE        WIND
 DAMSTAB      GROUND       LWL              SAVE         TORQUE       WRITE