Reference Codes - all you need to know about...

Reference Codes (RC) are documented by Mincom under 3001-"General User reference" manual.

Tek-Tips thread: thread440-96218

Here are our notes on RC:

1. RC Explained
2. RC Questions and Answers (Concerns/Security/Limitations)
3. RC Practical Examples

1. RC Explained
=========================================================
RC are a facility used in order to:
- link two existing Mincom-defined entities (eg: incident and work group) that are not normally related in the standard version of MIMS
- attach any new, user-defined field (characteristic) to an existent Mincom entity, eg: attach the ôWeather Conditionö field to Incident; the new field can store for example values from a user-defined table on MSF010.

The RC facility expands on the "User Definable Fields" present on some MIMS screens. The problem with the user definable fields was their severe limitations such as : limited number of fields, eg 4 fields only; data type was alphanumeric only; validated only against MSF010. All these limitations are gone with RC. The drawback of RC is that they are not displayed on the same screen and involve some degree of window navigation.

Terminology
entity: standard Mincom objects, eg: incident, work group, employee

target entity: the standard entity that has its characteristics expanded by attaching reference codes (eg: the work order entity on msf620)

reference code entity code(in short: ôentity codeö): a Mincom table code that identifies a target entity for the purpose of linking new characteristics to it. The ôentity codeö is stored on MSF010 table "RCEN". Eg: ôINCö is the Mincom standard entity code for the ôincidentö entity on MSF510. It is possible to define more than one entity codes to one target entity (eg both "INC" and "IN2" for MSF510 incidents). Table RCEN will store the codes for both Mincom and Client entities (see definitions below).

reference code parameters (in short: ôreference codesö): the actual new field (characteristic) attached to a target entity, thus expanding the MIMS model beyond its standard design; the reference code has a definition record on MSF070 that can present it as various things such as:
- another MIMS entity (validated against ôdatabaseö)
- a standard MIMS table (validated against MSF010)
- a user defined MIMS table (validated against MSF010)
- numeric information (various numeric formats)
- free text field (no validation)

Reference code parameters are defined against the entity code by using program MSO070; they are identified by a ôreference numberö (eg 001, 002, etc) and have a description, field width, field type, validation criteria and other characteristics attached, of which the following two may be more important:
- ôallow alternate searchö (for Mincom entities where alternative search by reference code is programmed by Mincom in the entityÆs review menu): this will allow to search based on the reference code instead of the entityÆs key. Eg: if a ôClient W/O numberö is attached to MSF620, then MSO621 Option 5 - Search by Reference Code becomes enabled and will allow to search for a work order with Client W/O number equal to æXA7923Æ.
- ôallow standard textö: will allow to attach standard text on MSF096 to the actual values stored in the reference code. Eg: in the situation above, one can attach an extended description to the Client W/O number similar to the normal ôextended textö facility that is normally available against the Mincom W/O number

Example:
- target entity: msf510 Incidents
- entity code : "INC" (standard Mincom entity)
- the client defines reference code ô001ö as "Responsible Work Group". This will implement a relationship between msf510 and msf720 work group record, if the client uses ôSpecial Edit Typeö field on msm070a to request validation against ôGROUPö; this is similar with the validation of MSF081 request parameters. The relationship is not enforceable, ie it is up to the user to record or not the work group for an incident.

Program MSO070 is used to define reference code parameters for both Mincom and Client entities (see section 3 below).

reference code parameter values: the actual values stored into reference codes. Eg: work group ô11ö has been entered into ôresponsible work groupö reference code for incident no ô4ö. Then "11" is the RC "parameter value".

Mincom entity: an entity code pre-defined by Mincom and hard-coded in the screens dealing with its target entity. The target entity will have action code ô9ö available on its screens. The entity code is still required to be present on table MSF010/öRCENö. Eg: "INC" is a Mincom entity code associated with msf510 Incidents. The entity code value "INC" can be found in the entityÆs screen source code. The advantage with predefined functionality is that reference code values can be accessed directly from the target entityÆs screen via an action code.

Client entity (also called "User-defined entity"): an entity code associated with a table for which reference code functionality was not pre-defined by Mincom. The client creates the entity code and manages the whole process of implementing it and maintaining its records. Eg: the ôInjuryö table msf514 has no Mincom-defined reference code functionality; this can be seen as the action code ô9ö is not available on the injury screens. If reference codes need to be recorded for Injury, the client needs to create an entity code, say "INJ", in MIMS. Maintaining the parameters values for client entities cannot be actioned from the target entityÆs screen; it occurs from the MIMS prompt by calling dedicated programs MSO071(maintain) & MSO072(review)

Program MSO074 can be used in order to review the reference code parameters for both Mincom and Client entities. However for Mincom entities it is more convenient to use action code æ9Æ present on the target entityÆs screen.


2. Questions and Answers
=========================================================

Questions:

1. Could you please list any technical concerns you may have with using Reference Codes to capture operational targets in MIMS?

2. I'm also wondering what security access options would be available to us to limit users to specific User-defined Entities.

3. Please advise if there are any limitations to the number of entities that can be created.

Answers:

I have no concerns about using reference codes in MIMS.

1. there is no practical limitation to the number of client entities created eg OHT, WDE, PPL, etc.(in fact there is a limitation set to the number of combinations achievable on 3 character codes). Common sense should be exercised so that duplicate entities are not created eg if same information is required for several work groups, one does not create distinct entities for each work group. If a Mincom entity can be used, a client entity should not be created for the same purpose. Mincom entities have the advantage of being directly accesible via action code '9' from MIMS screens.

Reporting ability:

RDL coding for reporting of reference code is relatively simple
CorVu queries using msf071 in isolation will be relatively easy to design. However in order to report reference codes against the associated entity eg MSF620 it will be required to either link msf071 to the entityÆs table, or to build complex queries from joined simple queries. It is likely that MSF071 cannot be linked directly and that some sort of knowledge library manipulation is required.

There are some shortcomings of the current MIMS design (version 4.1):
- very few tables have Mincom entities pre-defined (and associated action code functionality on MIMS screens)
- client entities cannot be accessed from the targetÆs screen via an action code
- no facility for data validation at entry of values in the record keys of client entities (MS0071)
- useful width for record key descriptions for client entities is limited to 15 characters (see MSM071A)


2. Security: it is possible to create a security profile for each entity and then map global profiles or user profiles against the entity's profile so that only particular users are granted access to the entity. For more on security refer to MIMS system administrator.

Auditing: it is possible to audit access to RC records. This can be done on two levels: (i) as MIMS stores internally the user id, date & time of LAST change to a reference code value on msf071. (ii) if all changes not only the last one need to be audited, set flag ôAudit Y/Nö on MSM070A to 'Y' - this will cause MIMS to write before and after images for every change to the MIMS Audit file.

3.1 Storage: there may be limitations to the allocated database space for table msf071 that records RC actual values. Each record is 163 bytes (ie to record one piece of statistics). Refer to MIMS Sysadmin with estimates of transaction volumes.

3.2. MIMS Limitations: following limitations apply to current design of MIMS:
- max number of keys for a client entity: 6
- max size of screen literals for a client key description: 15 characters
- total size of all keys: 34 characters
- max number of parameters that can be defined against an entity : 999
- no type validation on entry of data in the key fields for client entities


3. RC Practical Examples
=========================================================

3.1 We create a client entity called WDE in order to record Period Estimates for work orders.
3.1.1 The entity is created using MSO010 on table type RCEN:

Table Type RCEN Reference Codes
Table Code WDE
Table Code Description Work Order Prd Estimates
Question Pos. Reply
Table Type (Mincom/Client) C
Activity Status (Active/Inactive) A
Is there a Description for the Entity (Y/N) Y
Number of Parts in Key 4
Size of Key (Part 1) 04
Size of Key (Part 2) 08
Size of Key (Part 3) 04
Size of Key (Part 4) 02
Size of Key (Part 5) __
Size of Key (Part 6) __


3.1.2 We create the screen descriptions for the four components of the primary key of the WDE reference code. The descriptions are created using MSO010 on table type RCEL:

Table Type RCEL
Description Reference Code Entity Literals

Table Code Table Code Description
WDE01 District ID
WDE02 Work Order
WDE03 Fin. Year CCYY
WDE04 Fin. Period MM


3.2.MSF070: Create the Reference Code Parameters
Note: this same screen is used to create, modify and delete records
We shall create following parameters
001 Labour Cost Estimate
002 Material Cost Estimate
003 Other Costs Estimate

Below we show only the entry for 001 - Labour

Entity Type WDE Work Order Prd Estimates
Reference No. 001
Short Name LABOUR
LITERAL:
Screen Literal LABOUR COST ESTIMATE
Repeat Count 001
ENTRY/EDIT DETAILS:
Length 10
Field Type N numeric
Special Edit Type DEC2 only 2 decimal places are allowed
Audit N (Y/N) Display Desc. N (Y/N)
Range test: Low 0.00 High 0.00
Table Test N (Y/N)
Error Table Type
Alternate Access N (Y/N)
Allow standard Text Y (Y/N)

Note: MSO074 is the corresponding Review program:

Entity Type WDE Work Order Prd Estimates

Ref
No. Short Name Screen Literal Len Type
001 LABOUR LABOUR COST ESTIMATE 10 DEC2
002 MATERIAL MATERIAL COST ESTIMATE 10 DEC2
003 OTHER OTHER COSTS ESTIMATE 10 DEC2

3.3.MSF071 Maintain reference Code Values for Client Entity

We create estimates for work order TA20002 and financial period 01/2001:

MSM071A:
1. Create Reference Codes for User Defined Entity
2. Modify Reference Codes for User Defined Entity
3. Delete Reference Codes for User Defined Entity

ENTER Option 1
Entity Type WDE Work Order Prd Estimates
Entity Value District ID LCK
Work Order TA200002
Fin. Year CCYY 2001
Fin. Period MM 01

MSM071B:
District ID LCK
Work Order TA200002
Fin. Year CCYY 2001
Fin. Period MM 01

001 LABOUR COST ESTIMATE 110.00____
002 MATERIAL COST ESTIMATE 500.50____
003 OTHER COSTS ESTIMATE 200.00____

Note: MSO072 is the corresponding Review program