Definitions 2 Tab

"Definitions 2" Tab - Advanced Settings

This whole Tab is part of advanced settings and won't be visible if the basic interface is set.

In the box "Audit File variables", you can specify names for the fields that serve a purpose in the Audit file. This gives you the flexibility to use your own field and key names in the Audit files declared in the dictionary, and it gives you the option to add additional fields not included in the original Audit file.

•        Identification: This is the field that contains the unique ID for the audit records. Normally it is a type LONG field.

•        Audit file auto numbering: If you use an ISAM file, you should always check this option. The audit file is normally auto numbered. This means that when a new record is added to the audit file, the system finds the last record stored, add 1 to the identification field and will store the new record with the new unique number. This operation is not done transaction framing, so it in a multi user environment it is possible that in the time between  reading the last file and the recording of the new one, someone else might have used your number. The auditing system will detect a situation like this and will try to deal with it by retrying the operation.

But if you use an SQL file and you decide that the server will take care of the auto numbering process, you may uncheck this mark so that the template doesn't try to auto number the record. If you decide to go this route you have to define the field as autonumbered (identity) in the SQL engine. If you don't activate this option and you forget to define this field as an identity field in the SQL database, you will get an error as the moment you add the second record to the audit file.

Use GUID method: if you store the audit file in a SQL database, you may want to use this option to automatically generate a GUID identification. If that is the case, the "Identification" field has to be adecuate to store a GUID, not a LONG but a STRING(16) or CSTRING(17). A GUID value will be automatically generated by the template (instead of auto numbering the key).

•        Auto numbering key: Specify which key in your Audit file is the key that has the auto numbering option on. Normally it is the primary key and it should only contain one component, the identification field.

•        File: Specify the field that will contain the name of the file that is being audited. It has to be a STRING variable that is big enough to store the longest name of all the files you have in your dictionary. If you have files with names that are longer than 20 characters, you have to increase this field’s size.

Note: If you change this field’s length, you have to update the Audit file as well as the other 2 audit files (New and Bck). You also need to update length of the FileName in the Queue_Buffer in the global declaration called FRGlobalData.

•        Date: Specify which field in the audit file will store the date that the record has changed. This field will be populated with the computer system date where the program is running. If the user tampers with the computer’s machine date, this will be reflected in the audit file. You can use the identification field to sort the operations in their proper order and that way detect the out of sequence date. This field would normally be a LONG.

Note: For SQL files, dates usually go into groups. If you "pick" a field inside a group with the lookup button, it won't be accepted because it lacks the prefix. Instead, you have to type it manually.

•        Date order Key: Specify which key is the key where the first field in the key is the date field. This key will be used for the "Audit Cleanup" process.

•        Time: Similar to Date except for the fact that it is using the system clock and not the system date..

•        User: This is the field in the audit file that stores the code or name of the user that is logged in to the system. Normally it should be the same as the global user variable. This variable is not mandatory: if you leave it blank no user information will be recorded. We choose to store the logged in user’s numeric code, but if you prefer to store the name, you should change this field to STRING and make it big enough to hold the value.

•        Workstation: This field in the audit file will store the computer’s windows name where the operation took place. This may be a STRING as long as you need to store the longest machine name you may have. You may leave this field blank if you don't want to record the workstation name.

•        Procedure name: This is the field in the audit file that stores the name of the procedure in your system that generated the operation. It is very useful to track the origin of this operation in your system. This may be a STRING as need to be big enough to store the longest procedure name you may have among all your apps. You may leave this field blank if you don't want to record the procedure name.

•        Operation: This is the field in the audit file that stores the operation type performed by the system. This value is set in the Translation .TRN file. By default, it may have the following values:

Beware!! Only the first letter is used by some internal processes, therefore if you translate this default values take care that the first letter of each option is always unique. Also, keep the length of these equates consistent with the length of the audit file "operation" field, or some comparisons may fail and the template might work incorrectly.

•        Search Key: Here you will store, in a STRING format, significant data that might be examined in a query or in the inspector program. Keeping in mind that depending on the data type the audit process is storing the records in their binary form, if you use fields (Like LONG or REAL) the data will be unreadable. Furthermore, if you compress the data, it will be completely unreadable. If you want to do a query or a search with SQL, this "search key" field will let you see some information from the record.

Index Search key: identifies the key in the Audit file that indexes the file by the Search Key field mentioned above.

•        Stored Record: This field stores the audited record. It may be a STRING or a MEMO (binary) field, but it has to be big enough to store the longest record (excluding memos) of all the files you have in your dictionary. You can obtain this value using the TXD Analyzer supplied program. If you need to increase the size of this field, then you have to change this field in the Audit file as well as the other two audit fields (New and Bck). You also need to update the length of the StoredRecord in the Queue_Buffer in the global declaration called FRGlobalData. If you fail to make all of them  the same size, you may lose audit data or it will be the cause of unpredictable results.

Memo label: Is the label of the memo fields in the audit file, without prefix and without the final numbers. For example, if you have two memo fields in the audit file, named AUD:MemoField1 and AUD:MemoField2, here you have to type MemoField. The length of each memo field should be as long as the longest of all the memos in all your files. You must change this field in the Audit file as well as the other two audit fields (New and Bck). You also need to update the length of the MEMO in the Queue_Buffer in the global declaration called FRGlobalData. (See the global "memos" field in General Tab). The example dictionary has two memos, if your system has more than two in any file, you should add Memofield3, MemoField4, etc. to the audit files and increase the DIM value in the "MEMO" field in the global data area. See Using TXD Analyzer for obtaining this information automatically.

Fields  for "changed fields"

If you select the "Changed fields" or the "Mixed" operation mode for the template, you will need the following fields in your audit file:

Field name: This one will store the name of the changed field. By default is a STRING(40), you may change it in the DCT if you have larger (or far shorter) field names.

Field Type: The system will store here the type of the field, this information is necessary to retrieve it.

Field ordinal pos: This is the ordinal location of the field inside the whole record structure. It has to be a signed field in case it is a Memo or Blob, as their Ordinals are negative numbers (A SHORT will normally work). This field is used as well to identify if the stored information is a Full Record (0 value) or a Changed Field (Any value not zero).

Field cardinal pos: If the field is part of an array, this would be the element inside the array. For example, if you have a field dimensioned as DIM(3), and you changed the second element, this would contain the value 2. If you have a DIM(3,3), and you change the element (2,1), this field will take the value of 4, as in the record structure the fields are repeated one after the other in order, so you will have the field with the same name as (1,1), (1,2), (1,3), (2,1), etc.

PK name: Is the name of the file primary key that allows to identify the record in unique way - it is used to restore the changed value if you want to recover from the audited data.

Decimal length: The number of numeric places if the stored field is a decimal type field.

Decimal places: The number of decimal places if the stored field is a decimal type field.

Old value (BLOB): A BLOB field to store the "old" value of a changed field.

New Value (BLOB): A BLOB field to store the "new" value of a changed field.

PK value (BLOB): Is the content of the file primary key that allows to retrieve the record using the primary key of the audited file - it is used to restore the changed value if you want to recover from the audited data.

Important: if you are upgrading from FullRecord 2.x, you won't have these fields: you have to add them to your audit file and convert it with any way you like (FM3 is ok, for example).

Note: if you will use the "FullRecord" mode and will never use the "mixed" or "change fields" modes, you can remove the extra three BLOB fields from the audit file, however the rest of the fields must be added anyway. In this case you may left the "blob" fields entries here empty.

Review the fields from the AUDIT file and from the global data area (FRGlobalData) in your dictionary, to verify that they fit your needs. You should not modify the audit fields that are not mentioned here (if you find any) or the template may stop working accurately.