Each DLL function in the SansGUI environment is defined with a single function prototype. The functions can be associated with an object or a part. It is more general to look at the function prototype from a part's point of view, depicted in the following diagram:
Except the Other Arguments box and dashed lines, which show "referring to" relationships, all the other elements in the diagram are SG_OBJ data objects. These data objects are:
self: the current part in which the function call is involved.
simCtrl: the data object of the Default simulation control object.
chgChild: reserved for future use.
refObj: the data object of a reference object that self is referring to, i.e., an attribute of the object reference type in self has the name or the path of refObj as its value.
adjObj: the data object of an adjacent part that is connected with self via a link. It can either provide self with input values or receive output values from self.
lnkObj: the data object of a link used to connect self to an adjacent part.
When the function is associated with an object, there is no adjObj or lnkObj involved. When the function call happens in an editing session, as opposed to during a simulation run, only self and simCtrl are reliable for processing. SansGUI also tries to resolve object references as complete as possible and passes the reference objects in refObj to the DLL functions during the model construction time.
All DLL functions are implemented with the SG_SIM_FUNC function prototype. The function return value SG_RET_CODE will be discussed in the DLL Function Return Values section.
typedef SG_RET_CODE (SG_SIM_FUNC)
(
SG_OBJ *const self,
SG_OBJ *const simCtrl,
SG_OBJ *const chgChild,
SG_OBJ *const refObjs[], const INT *const piRefObjs,
SG_OBJ *const adjObjs[], const INT *const piAdjObjs,
SG_OBJ *const lnkObjs[], const INT *const piLnkObjs,
TCHAR *const cMessage, const INT iMsgLen,
TCHAR *const cCommand, const INT iCmdLen,
SG_FILE *const pOutFile
);
Some explanations follow:
The refObjs, adjObjs, and lnkObjs arguments are arrays to pass reference objects, adjacent parts, and connected links, respectively.
The numbers of reference objects, adjacent parts, and connected links are in the piRefObjs, piAdjObjs, and piLnkObjs arguments. They are pointers to integers rather than simple integers. To access the number of adjacent parts, for example, use *piAdjObjs. The numbers basically indicate the sizes of the corresponding arrays.
The refObjs array contains pointers to all reference objects referred to by self. They are listed in the same sequence as the class attributes.
The number of adjacent parts and connected links should be the same. Each adjacent part has a corresponding link with the same array index. For example, lnkObjs[2], if existing, connects to self with adjObjs[2]. If the direction of the connection or the ports used for the connection are needed, use the first SG_TYPE_LINK value in lnkObjs[2]. The SG_TYPE_LINK specification can be found in the Object Data Representation section in Chapter 1.
The cMessage argument is a string buffer allocated by SansGUI for the DLL function to return a message so that SansGUI can display it when requested. The string size is defined by a macro SG_STR_LEN plus 1 with the last character being NULL, the terminating character. SG_STR_LEN is currently defined as 1023 in SGdll.h. The DLL function should manipulate the cMessage string with maximum length of SG_STR_LEN. The constant iMsgLen is always set to SG_STR_LEN.
Both cCommand and iCmdLen are reserved for future use.
The pOutFile pointer, if not NULL, points to an opened output file for DLL functions to write output to. The file name used for the opened file is specified by the user in the simulation control object.
The Fortran API function implementation is similar to the C function prototype. Instead of a defined prototype for all DLL functions, they are implemented with the specific names of the entry points. More on the DLL Function Entry Points can be found in the next section. Here, we use the SG_xInit function as an example. All the other functions should be implemented the same way except for the names. This implementation also uses a Compaq/Digital Visual Fortran (CVF) specific feature to export SG_xInit function in the DLL. SansGUI requires the function names be case-sensitive.
integer function SG_xInit(self,
& simCtrl, chgChild,
& pRefObjs, iRefObjs,
& pAdjObjs, iAdjObjs,
& pLnkObjs, iLnkObjs,
& cMessage, cCommand,
& pOutFile )
!DEC$ IF DEFINED (_DLL)
!DEC$ ATTRIBUTES DLLEXPORT :: SG_xInit
!DEC$ END IF
include "SGdllf.h"
The difference between the Fortran implementation and the C prototype are:
The cMessage argument is not followed by the length of the string buffer. The C to CVF Fortran function call implicitly merged the length information into the Fortran character array.
The pOutFile pointer points to a C standard I/O file, which is not compatible with Fortran logical units in file I/O. Fortran code should not use this file pointer for output.
The function arguments are defined in SGdllf.h with some access pointers for convenience. The inclusion of this file is recommended, unless the necessary declarations are duplicated in each function.
type (SG_OBJ) self, simCtrl, chgChild
integer :: iRefObjs, iAdjObjs, iLnkObjs
integer(4) :: pRefObjs(iRefObjs)
integer(4) :: pAdjObjs(iAdjObjs)
integer(4) :: pLnkObjs(iLnkObjs)
character(*) :: cMessage, cCommand
integer(4) :: pOutFile
type (SG_OBJ) :: adjObject
POINTER(PTR_adjObject, adjObject
type (SG_OBJ) :: refObject
POINTER(PTR_refObject, refObject
type (SG_OBJ) :: lnkObject
POINTER(PTR_lnkObject, lnkObject
To access the data members in the SG_OBJ data objects, please consult SG_OBJ Data Access in Fortran in the SG_OBJ Data Structure section. Accessing the zValues array in the second adjacent part's data object, for example, can be done via the PTR_adjObject and a PTR_adjValues pointers:
type (SG_VALU), dimension(*) adjValues
POINTER(PTR_adjValues, adjValues)
PTR_adjObject = pAdjObjs(2)
PTR_adjValues = adjObject%pzValues
After these statements, the adjValues is the data array for the data object of the second part.
The DLL function may return any one of the following values:
SG_R_OK: to indicate that the function call is successful. The simulation will be continued and no other actions will be needed.
SG_R_LMSG: to indicate that there is a message to be logged in a Message View and, for Data Editing Functions (SG_xEndEdit and SG_xLoad), displayed in a pop-up message box. When it is returned from an Execution or an Evaluation Function during a simulation run, the message is shown to the user in the Message View, and the simulation continues without any interruption.
SG_R_PAUS: to indicate that the simulation should be paused to give the user the options of continuing or quitting the simulation. A message may be displayed.
SG_R_STOP: to indicate that the simulation is about to be terminated, due to some errors or certain termination conditions found by the simulator.
SG_R_VERS: to indicate that the class version does not match the one expected by the simulator. It is a severe error and the simulation will be terminated.
SG_R_SCHM: to indicate that the SG_OBJ and SG_VALU data structures have a different version than expected. It is a severe error and the simulation will be terminated.
SG_R_ERR: to indicate a severe error encountered by SansGUI, such as a run-time exception during the execution of the DLL function. The simulation will be terminated.
SG_R_* | 24 Bit Error Number: to include a simulator error code in the error message displayed. It can be any number from 1 to 0x00FFFFFF. The highest byte is used by the SansGUI return codes defined here with the SG_R_ prefix. Do not, however, add any error number to SG_R_OK because it will change the return value to indicate an error.
 |
 |
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.