• dtSessionRecord: An ADO.NET DataTable containing the session record for the current CATSWeb user. This recordset contains many parameters which are useful for record filtering or other applications. To see all that is available, examine the CATSWeb Sessions table or Database Schema Document. Here are some of the most useful fields:
  • ConnectString: The ADO connection string used to connect to the CATSWeb database. Utilizing this string for your own CATSWeb connections will assure that the procedure functions even if the system administrator makes changes, or if the DLL is deployed in a different CATSWeb system.a different CATSWeb system..
  • EmployeeID: The Employee ID of the current user.
  • EmployeeName: The name of the current user.
  • Department: The department of the current user.
  • EMailAddress1: The E-mail address of the current user.
  
  
• formType: A short integer parameter specifying the type of form the function is getting called from or for. Utilizes the CWEB_FORMTYPE_ set of values that are described within the CATSWeb Public Constants. See below for some examples.

  Form Type	Value	Constant
  Issue	1	CWEB_FORMTYPE_ISSUE
  Actions	4	CWEB_FORMTYPE_CA
  Subtasks	55	CWEB_FORMTYPE_SUBTASKS
  Subforms	108	CWEB_FORMTYPE_SUBFORM
  Notes	10	CWEB_FORMTYPE_NOTES
  Links	36	CWEB_FORMTYPE_LINK
  File Attachments	37	CWEB_FORMTYPE_ATTACHMENT
  Signatures	46	CWEB_FORMTYPE_SIGNATURE
  Group	26	CWEB_FORMTYPE_ADMIN_GROUP
  Department	24	CWEB_FORMTYPE_ADMIN_DEPARTMENT
  Personality	170	CWEB_FORMTYPE_ADMIN_EMPLOYEE_PERSONALITY
  Employee	23	CWEB_FORMTYPE_ADMIN_PERSONNEL

  
  
• category: Variable length string.

  Operation	Value
  List Values	The category of the form.
  Default Value	The category of the form.
  Drill Down	The category of the record being drilled down on.
  Event Hook	The category of the record being operated on.
  Post-method Call	The category of the record being operated on.

  
  
• opCode: A short integer variable which indicates the type of operation in process when the function is called. Utilizes the CWEB_OPCODE_ set of values that are described within the CATSWeb Public Constants. See below for some examples.

  Operation	Value	Constant
  List Values	1	CWEB_OPCODE_LIST_VALUES
  Default Value	2	CWEB_OPCODE_DEFAUALT_VALUE
  Drill Down	3	CWEB_OPCODE_DRILLDOWN
  Event Hook	4	CWEB_OPCODE_EVENT_HOOK CWEB_OPCODE_AUTO_LOOKUP CWEB_OPCODE_INITIAL_CALL
  Post-method Call	5	CWEB_OPCODE_POSTMETHOD_DLL_CALL

  
  
• theTableField: Variable length string.

  Operation	Value
  List Values	The name of the field that requires the data.
  Default Value	The name of the field that requires the data.
  Drill Down	The name of the field or control that was clicked by the user.
  Event Hook	The string equivalent of the action code. Utilizes the CWEB_ACTION_ set of values that are described within the CATSWeb Public Constants. See below for some examples. CWEB_ACTION_ADD (1) CWEB_ACTION_EDIT (2) CWEB_ACTION_DELETE (3)
  Post-method Call	The string equivalent of the action code. Utilizes the CWEB_ACTION_ set of values that are described within the CATSWeb Public Constants. See below for some examples. CWEB_ACTION_ADD (1) CWEB_ACTION_EDIT (2) CWEB_ACTION_DELETE (3)

  
  
• theTableFieldValue:  Variable length string.

  Operation	Value
  List Values	Empty string.
  Default Value	Empty string.
  Drill Down	the value of the field that was clicked by the user.
  Event Hook	The string equivalent of the record ID (e.g. IncidentID, ActionID, etc.), unless the Event Hook is for a record being newly added. The string will be empty in that case since a record ID has not yet been assigned.
  Post-method Call	The string equivalent of the record ID (e.g. IncidentID, ActionID, etc.), even when a record was newly added.

  
  
• dtRecord: An ADO.NET DataTable.

  Operation	Value
  List Values	Nothing.
  Default Value	Nothing.
  Drill Down	A complete copy of the record being drilled down on.
  Event Hook	All the values submitted by the user. ActiveX DLL and Web Service Data Links that are used by Display Parts are passed the Display Part configuration record.
  Post-method Call	All the values submitted by the user, as modified by any Event Hook operations.

  
  
• dtParams: An ADO.NET DataTable.
  

  Operation	Value
  Event Hook	In most cases, this parameter will be set to Nothing. ActiveX DLL and Web Service Data Links that are used by Display Parts are passed the Issue/Action/Subtask record.
  Post-method Call	In most cases, this parameter will be set to Nothing. Post-method Call Event Hooks that run during Signature Controlled events can test values within this parameter to determine if the final signature has been added. If any signature controlled operations completed, dtParams will be open and contain a single record for each operation that completed. Each record will contain a single field (AsxCompletedApprovalOpCodes) that will contain the Approval Op Code of the operation.

  
  
  • AsxCompletedApprovalOpCodes values:
    

  Record Type	Approval Type	Value	CATSWeb Constant
  Issue	Issue Submission Approval	1	CWEB_APPROVAL_OP_ISSUE_SUBMISSION
  Issue	Preliminary Disposition Approval	2	CWEB_APPROVAL_OP_PRELIM_DISP
  Issue	Final Disposition Approval	3	CWEB_APPROVAL_OP_FINAL_DISP
  Issue	Final Issue Approval	4	CWEB_APPROVAL_OP_FINAL_ISSUE
  Action	Action Completion Approval	24	CWEB_APPROVAL_OP_ACTION_COMPLETION
  Action	Action Closing Approval	22	CWEB_APPROVAL_OP_ACTION_CLOSING
  Subtask	Subtask Completion Approval	41	CWEB_APPROVAL_OP_SUBTASK_COMPLETION
  Subtask	Subtask Closing Approval	42	CWEB_APPROVAL_OP_SUBTASK_CLOSING

  
  
• colHTML - Collection. This is not a standard .NET collection, but is actually a special AssurX collection, that is very similar to a VB6 VBA collection. See ASXCollection for details.
  
  During some operations, it will contain IIS Server Variables on input.
  

  Operation	IIS Server Variables	Value
  List Values	N	Nothing.
  Default Value	N	Nothing.
  Drill Down	Y	On output: your function code may add entries to the collection that can modify or replace some or all of the Field Captions or HTML that CATSWeb displays to the user. See below for more information.
  Event Hook	Y	On input: will contain field property changes made by previous event hooks. On output: During Form Preload, Form Load or Form Reload operations: Your function code may add entries to the collection that can modify or replace some or all of the Field Properties or HTML that CATSWeb displays to the user. See below for more information.
  Post-method Call	Y	Nothing.

  
  
• errString - On input, this variable-length string parameter will be empty. Normally your procedure code should not modify this parameter.
  • Event Hooks: .If called as an Event Hook, setting this string to any value other than empty will cause the recordset returned to CATSWeb to be ignored. However, no error in CATSWeb will be triggered or displayed.
  • Drill Down Links: If your function is being called from a drill down link, and it encounters an error, it should handle the error and fill the errString with error text. CATSWeb will display the text to the user in an error message.
    • Note that because of the way CATSWeb calls the function, it cannot read values from the Error object that would be raised from the DLL function. The error must be handled by the function. The only way for CATSWeb to display a specific error message to a user accessing a drill down link is via this parameter.
  • If called for any other reason, this parameter will be ignored.

When the DLL function is called by CATSWeb, the colHTML parameter will contain most of the IIS server variables, such as HTTP_USER_AGENT, REMOTE_ADDR, etc. On output, your function code may add entries to the collection that can modify or replace some or all of the Field Captions or HTML that CATSWeb displays to the user.

• The DLL function can add HTML strings to the colHTML collection for return to CATSWeb. The strings must have specific keys (names). CATSWeb looks for the named strings in the collection, and if present, uses them to modify the HTML.
• For example, this code in the DLL function causes CATSWeb to display a custom title, overriding the title specified in the drill down link definition:

colHTML.Add("This is My Custom Title", "!TITLE!")

CustomValidation = Nothing
strErr = theFunctionName + " Error: " + StackErrNET(ex)

'CLEAN UP

Back to Top

Registering for Post-method Calls (Standard Method)

When a .NET Class DLL function is called by an Event Hook (via an ActiveX DLL Data Link, ActiveX DLL with Parameters Data Link or Web Service Data Link), it is called during the initial call of the CATSWeb process, prior to any action CATSWeb may need to take. This includes standard validations that CATSWeb usually performs, as well as the actual process of adding, editing or deleting the record. In some applications it is desirable for the function to be called after the CATSWeb process has completed (such as after a record has been successfully added).

• For example, if the function is designed to send a custom E-mail message after a new record is added, the appropriate time for doing so is after the submission passes all validation tests.
  
• CATSWeb provides a means for a DLL function to register itself (or a different function) for a post-method call at the end of the process. The registration occurs during the initial call from the Event Hook. An Alternate Method is also available.

Dim theFunctionName As String = "SendCustomEmail"
Dim strErr As String = vbEmpty

Dim dtTemp As New System.Data.DataTable = Nothing
Dim temprow As DataRow = Nothing
Dim theFieldName As String = vbEmpty
Dim theSubmittedCategory As String = vbEmpty
Dim theValidationErrorMessage As String = vbEmpty

Case CWEB_OPCODE_EVENT_HOOK

' We are being called in the beginning of the CATSWeb process.
' The only action we need to take here is to pass back a reference to
' ourselves (our progID and function name) in the returned
' recordset so that we can be called again at the end of the
' process.

' Begin by creating a ADO.NET DataTable  from scratch that we will later
' return back to CATSWeb.
dtTemp = New DataTable("Temp")

'Add a column to the DataTable
dtTemp.Columns.Add(CWEB_FLD_ASSURX_POSTMETHOD_PROGID, Type.GetType("System.String"))

'Add a column to the DataTable
dtTemp.Columns.Add(CWEB_FLD_ASSURX_POSTMETHOD_PROPERTY, Type.GetType("System.String"))

' Add our data to the DataTable. We will just
' be returning back a single record containing our values
' in the appropriate fields.

' Create a new row in our DataTable.
temprow = dtTemp.NewRow()

theValidationErrorMessage = "Your entry in the FooBar field is not valid."
temprow(CWEB_FLD_ASSURX_POSTMETHOD_PROGID) = "Sample.Class"
temprow(CWEB_FLD_ASSURX_POSTMETHOD_PROPERTY) = theFunctionName

' Add our new row to the DataTable.
dtTemp.Rows.Add(temprow)

' We are done. Return our DataTable back to CATSWeb.

SendCustomEmail = dtTemp
Exit Function

Case CWEB_OPCODE_POSTMETHOD_DLL_CALL

' We are being called at the end of the process.

{Put code here to send custom E-mail}

Case Else

' We are being called for some unknown reason. Exit now.

Exit Function

Back to Top

Registering for Post-method Calls (Alternate Method)

The ActiveX DLL with Parameters Data Links offer an alternate method of registering for post-method calls. This method causes the optional parameters stored in the data link record to be passed to the DLL in colHTML, just as it is during the initial call. To use this method, return the following information in the function's output .NET DataTable.

• CWEB_FLD_ASSURX_POSTMETHOD_PROGID ("AsxPostMethodProgID") - Return the name of the data link, instead of the programmatic ID.
  
  
• CWEB_FLD_ASSURX_POSTMETHOD_DATA_LINK ("AsxPostMethodDataLink") - Return "-1" to signal CATSWeb to make the post-process call using the data link's configuration data.
  
  
• CWEB_FLD_ASSURX_POSTMETHOD_PROPERTY ("AsxPostMethodProperty") - Not used. This field may be Null or be entirely omitted from the recordset.

Troubleshooting with DumpDataHTML

It is often desirable to know exactly what values are being passed into a .NET Class DLL during various Event Hook calls.AssurX's validation DLL (AssurXValidation.dll) contains a property named DumpDataHTML which implements a universal data dump routine.

• When it is called as an Event Hook, it creates an HTML file that contains a listing of the all of the parameters values that are passed to the function, including dtRecord, dtSessionRecord, colHTML. Where applicable, it automatically registers itself for a post-process call, then creates a second file showing a dump of the data for the post-process phase. The dump files are named in a manner that allows the data for different events to be easily distinguished (e.g., DumpDataHTML_Issue_Add_InitialCall.htm, DumpDataHTML_Issue_Add_PostProcessCall.htm, DumpDataHTML_Issue_PreLoad_View_InitialCall.htm).

To utilize DumpDataHTML, do the following:

• Locate AssurXValidation.dll on the CATSWeb CD-ROM or electronic media. Use Windows Explorer to read the version number and assure it is 8.00 or higher. If it has a lower version, obtain a new file from later CATSWeb Service Packs (Build 18 min).
  
  
• Copy AssurXValidation.dll to your CATSWeb installation directory on the Web server. If a prior version already exists, you may need to restart IIS to eliminate possible file sharing violations during the copy process.
  
• On the Web server, open a command window and change to the CATSWeb installation directory. Use REGASM to register the DLL,
  
• Add a new ActiveX DLL Data Link with the following settings:
  • Data Link Name - AssurXValidation_DumpDataHTML
  • Programmatic ID - AssurXValidation.ValidationClass
  • Property Name - DumpDataHTML
    
• You may now use this data link in any Event Hook. Make the Event Hook active during the events that you wish to receive data dumps for.
  
• When DumpDataHTML is called, by default it will create its dump file in the CATSWeb installation directory on the Web server. This means that the IIS account must have permission to read, write and delete files in this folder, else the file will not be created. If you prefer to have the dump files created in a different location, you may:
  
  • For 64 bit Windows systems systems:
    • Add a string value named "DumpDataHTMLFolder" to the "HKLM\Software\Wow6432Node\AssurX\CATSWeb V8" registry key (create the key first if it does not exist) and set the value to a folder location using a full path (ex: "C:\Temp").
    • Assure that the IIS account has permission to read, write and delete files in this folder, and assure that it can read the registry key.