PROIV Developer Helper Functions

DEVELOPER

There are several critical processes and attributes which require updating that are either too complicated to be adequately covered in this document, or too difficult for the developer to implement without the likelihood of errors.

For this reason, a number of Helper Functions have been provided to ensure that critical PROIV Developer data can be kept updated by third party utilities.

Function Maintenance Help Functions

VIPCHKLG Parses a single function or Global Logic and updates cross-references

VIPEVENT Update Logic ID / FnKey on Event Points

VIPLINKS Rebuild linkage information for a function

VIPTAGRN Renames the Tag Name of Dynamic, Cycle, Static and Static Groups objects

Data Dictionary Maintenance Help Functions

VIPRDVAR Read dictionary information for a File Variable

VIPWRVAR Write dictionary information for a File Variable

VIPRNVAR Rename/copy dictionary information for a File Variable

VIPDLVAR Delete a File Variable from the dictionary

Rebuild File Definitions and Global Logics

VIPFLBLD Build a File Definition to the Native PROIV files

VIPGLBLD Build a Global Logic to the Native PROIV files

Logic Validation and Cross-References Update

Logic should always be parsed after changes have been made to it. This is to ensure that it is valid, and also to rebuild the dependant cross-reference tables that PROIV Developer uses. The Helper Function VIPCHKLG can be called to parse a single logic line, or the whole logic, and will update the relevant tables.

Helper Function VIPCHKLG

Description Parses a single Function or Global Logic and updates cross references.

Parameter Type	Variable Name	Dimension	Length	Description
In	$FunctionName		32	Name of function
In	#LogicId		3	Function Logic ID to parse. value range is 1 to 999.
In	$GlobalLogic		32	Name of Global Logic
In	#ParseOnlyLineNumber		3	When set, parses this line only. Value range is 1 to 9999.
Out	$LogicIsValid		1	Parser Return: Logic Is valid? (Y/N)
Out	$LogicHasLines		1	Parser Return: Logic Has Lines? (Y/N)
Out	$ErrorMessage		80	Parser Return: Error message
Out	#ErrorLine		4	Parser Return: Line at which error was detected

Notes

If both a function name and Global Logic name are passed to this update, the Global Logic is parsed in context of that function. This is normally required when the Global Logic references Object Tags, and ensures correct validation.
When a Global Logic name is specified, #LogicId is ignored and can be passed in as zero.
If the specified Function or Global Logic does not exist in PROIV Developer, an error message is returned.
A single line can be parsed by setting the #ParseOnlyLineNumber parameter.
For small logics, or those which do not contain many references to Object Tags or function calls, it may be more efficient to allow the whole logic to be parsed.
Logics are not allowed to contain gaps in their line sequences. If a gap is encountered then subsequent logic lines are automatically re-sequenced to remove that gap.
The update returns two Boolean flags to indicate if the logic is valid, and whether it has lines. If the logic is not valid, a description of the problem is returned in the $ErrorMessage parameter, and the line that it was found at is returned in the #ErrorLine parameter.
When parsing function logic, the Function Header file VIPBM01 should not be open for update. The exception to this is when it is held open in the same session to achieve a record lock, but the developer must then ensure that the write of the record is suppressed. The Logic Parsing process may update the @LOGIC_ID_USED array on the Function Header File.

Logic Assignment and Function Key on Event Points

This Helper Function should be used to update logic assignments on Event Points. It will update the information held on the Structure File, used by the Event view and when determining logic usage, and also the Logic ID’s status information, which is stored on the main Function Definition File.

This Helper Function should also be used to update the Function Key assigned to Dynamic icons and s. In this case it updates the Function Key detail held on the Structure File, which appears by the events view, and writes the Function Key number to the main Dynamic Object Data File, VIPBM05.

Helper Function VIPEVENT

Description Update Logic ID / FnKey on Event Points

Parameter Type	Variable Name	Dim	Length	Description
In	$FunctionName		32	Name of function
In	#LogicId		3	The Logic ID to be assigned, or that has had all lines deleted
In	$LogicHasBeenDeleted		1	Set to 'Y' when this logic has been physically deleted
In	$UpdateLogicUsedStatusOnly		1	Set to ‘Y’ to update/correct the Logic ID Used status on Function header
In	$GlobalLogic		32	Name of Global Logic to assign to the Event Point
In	#EventPoint		2	Event Point to assign the Logic ID or Global Logic (1 to 30) or 0.
In	$StructureSEQ6		6	The Structure Sequence number of the Object being updated
In	$FnKey_ActionControl_CycleTag		32	Tag name of the Cycle that the Function Key or Action Control belongs to when updating the Logic ID assigned to it.
In	#FunctionKeyNumber		3	Function Key that is being updated or being Assigned
In	$ActiveXObjectTag		32	Tag Name of the ActiveX object which is having an event updated
In	$ActiveXObjectInterfaceId		4	The ActiveX control’s Interface ID, normally @INTF_P4_ID
In	$ActiveXObjectEventId		12	The OS ID of the ActiveX objects event that is being updated. (@AX_PME_OS_ID)
In	$DocFormatGroupTag		32	Tag Name of Document Format Group
In	$ActionControlTag		32	Tag Name of the overloaded Action Control
Out	$ErrorMessage		80	Error message
In	$OpenAjaxEventName		200	Open Ajax event name

Notes

If the function name is not specified, or if the function does not exist in PROIV Developer, an error message is returned.
If an unsupported Event Point is passed to the Helper Function for a particular object, or insufficient key information is specified then an error message is returned.

When updating an assignment on an Event Point, certain information is required:

For Event Points 1 through 26 on structural objects (Cycles, Dynamics, Files, and Format groups) the 6 digit structure sequence number for that object must be specified.
For an Event on a Document Format Group, the Tag Name must be specified and the Event Point value must be 27 or 28.
For an Event on an ActiveX object, the keys to that ActiveX Object and the event must be specified. The Event Point value must be 29. If both a Logic ID and a Global Logic ID are specified, the Global Logic ID takes precedence and is assigned.
For a Function Key object, both the Cycle that it belongs to and the Function Key number must be specified. The Event Point value must be 30 and the Function Key number must be in the range of 33 through to 232. If both a Logic ID and a Global Logic ID are specified, the Global Logic ID takes precedence and is assigned.
For an Action Control object, both the Cycle that it belongs to and the Action Control Tag Name must be specified. The Event Point value must be 31. If both a Logic ID and a Global Logic ID are specified, the Global Logic ID takes precedence and is assigned. Refer to Event points and Logic Assignment for more detailed information on the Event Point values and the objects that support each of the Event Points.
Function Logic IDs assigned to Event Points can be in the range 1 to 9999, while specifying 0 will remove the existing logic assignment. When updating the Function Key value assigned to Dynamic icons or s, the Event Point value is 5 and the #FunctionKeyNumber parameter must contain a value in the range of -2 through to 232.
The Logic ID information for the specified Event Point is updated on both the function structure and also the Objects Main Attribute File. For example, if the logic is assigned to a Dynamic object then VIPBM05 is updated.
When updating logics assigned to Event Points on structural objects, it is recommended that the tool be driven from the Structure File as this contains all of the information by the Helper Function.
When the Event Point value is set to 0, the helper can perform two other useful functions:
If a Function Logic has been physically deleted, the Helper Function can remove all references to it from the function. To do this, specify the deleted Logic ID and set the $LogicHasBeenDeleted parameter to "Y". No other parameters should be specified.
Alternatively, the Logic ID Used status for a single logic ID can be updated or corrected. To do this, specify the Logic ID and set the $UpdateLogicUsedStatusOnly parameter to "Y". This will scan the function structure as well as Function Key and ActiveX events for references to the logic, and then update the Logic ID Used status array on the Function Header. No other parameters should be specified. Note that this does not reparse the logic to check if it is valid.
It is not permitted for both of the $LogicHasBeenDeleted and $UpdateLogicUsedStatusOnly parameters to be set to ‘Y’ at the same time.
When calling this Helper Function, the Function Header file VIPBM01 should not be open for update. The exception to this is when it is held open in the same session to achieve a record lock, but the developer must then ensure that the write of the record is suppressed. The Logic Assignment process updates the @LOGIC_ID_USED array on the Function Header File, and may update the Entry or Exit Logic of the function.
When a Logic ID is assigned to an Event Point, the @LOGIC_ID_USED array is updated to show that the Logic ID is referenced. If the Event Point already had a Logic ID assigned to it, then this logic is unassigned from that Event Point, the function is checked to see if it referenced elsewhere in the function and the @LOGIC_ID_USED array is updated accordingly. When a logic has been deleted, the @LOGIC_ID_USED array is updated to show that the logic is unassigned and undefined.

Rebuilding Function Linkage Information

There are a number of attributes across the Function Definition Files that are normally monitored by PROIV Developer and are used to generate the Linkage Tables. The data on this file is complex to maintain, and as it is used by the Linkage view and the Export process it should be kept up to date at all times.

Rather than document every attribute that must be monitored, and how to add or remove the data from the Linkage Table, a Helper Function is available that can be called after the function’s data has been changed.

This Helper Function can be called to update the linkage for either or both the function’s objects and logics. Rebuilding logic-based linkages will cause all of the logic in that function to be reparsed, which can be a lengthy process. If logic has not been altered then this part of the process is not necessary and can be disabled. If a few logics have been altered then they can be parsed individually with a separate helper.

Helper Function VIPLINKS

Description Rebuild Linkage Information for a Function

Parameter Type	Variable Name	Dimension	Length	Description
In	$FunctionName		32	Name of function
In	$ProcessLogic		1	Process logics for linkage information? (Y/N)
Out	$ErrorMessage		80	Error message

Notes

This update will rebuild all of the linkages information for a single function. Processing all logics in the function can be a lengthy task, so it is optional and is not processed by default. When logic processing is enabled, all of the logic in the function is reparsed.
Linkage information is always rebuilt for Dynamic objects, Function Keys and events on ActiveX controls when this Helper Function is called.
If the function name is not specified, or if the function does not exist in PROIV Developer, an error message is returned.
This update is best called at the conclusion of processing the function. If logic processing is enabled, then your tool would not need to also call the VIPCHKLG function for updated logic. Doing so would result in the logic having been parsed twice.

This update will also ensure that:

Logic Assignments held on the function Structure File match the logic assignments held on the objects main attributes file.
The information displayed in the Function Key Management and the Dropdown Menu Maintenance windows is correct.
When rebuilding Function Linkages, the Function Header file VIPBM01 should not be open for update. The exception to this is when it is held open in the same session to achieve a record lock, but the developer must then ensure that the write of the record is suppressed. The Linkage Rebuild process may update the @LOGIC_ID_USED array on the Function Header File.

Renaming Tags

Renaming tags in PROIV Developer can have wide ranging implications. Cycles and the File Accessors, Static objects associated with that object and logic statements can be all be affected. Tag renaming is a critical process in PROIV Developer and if done so incorrectly can result in corruption of the function.

Due to the complexity of ensuring that all affected objects, as well as PROIV Developer’s cross-reference tables are updated accordingly, the Helper Function VIPTAGRN has been supplied.

Helper Function VIPTAGRN

Description Renames the Tag Name of Dynamic, Cycle and Static objects

Parameter Type	Variable Name	Dimension	Length	Description
In	$FunctionName		32	Name of function
In	$OriginalTagName		32	Original Tag Name to rename from
In	$NewTagName		32	New Tag Name to rename to
Out	$ErrorMessage		80	Error message

Notes

This update should be used whenever an Object Tag requires changing. It ensures that all cross-reference tables and logic references are also updated.
The function should not be called when other PROIV Developer files are open for updating. Doing so may result in data being reverted back to the original values when those open files are written, causing corruption of the function.
In instances where it is unavoidable that other files are already open for update, it is the responsibility of the developer to ensure that any Tag Name attributes contained on them are updated as applicable.
If there is no object present in the function with the specified original Tag Name, or if one already exists with the new Tag Name, then an error message is returned. Object Tag Names must meet the same criteria as in PROIV Developer. For example, they cannot start with a number or contain spaces, and an error is returned if the new name is invalid.
Document and Report Format Groups can also be renamed with this Helper Function. They do not have restrictions on their naming format, as they cannot be referenced by logic. There are two default format groups in Reports and Documents which cannot be renamed; the Page Header Format Group, and the Page Footer Format Group.
Objects and Format Groups cannot share Tag Names and must always be unique.
If the function name is not specified, or if the function does not exist in PROIV Developer, an error message is returned.

Data Dictionary Maintenance

The Data Dictionary contains all of the File Variables that are used in File Definitions in PROIV Developer.

The primary function of the dictionary in Native PROIV was to provide the default length, dimension, fill code and special check logic for each variable when it was added to screens or reports.

In PROIV Developer, the dictionary now also holds a default object ‘shape’ for each variable, and this is used when adding that variable as a Dynamic object in a Screen function. The PROIV Developer Dictionary Files can have all the complexity as a Dynamic object in a function; they can have their own unique logics, error messages, interface maps and all of the associated cross references tables. Additionally, the dictionary entries can hold defaults for the external storage requirements for that variable.

At this time, only simple manipulation of the dictionary is available to the developer. The provided Helper Functions allow creation of new dictionary entries, copying of existing dictionary entries to new variable names (rename) and updating of standard dictionary information for the variable.

The Helper Functions are as follows:

VIPRDVAR Read dictionary information for a File Variable

VIPWRVAR Write dictionary information for a File Variable

VIPRNVAR Rename/copy dictionary information for a File Variable

VIPDLVAR Delete a File Variable from the dictionary

When each of the Helper Functions are called, an error message may be returned to indicate if the variable was not in the dictionary (on read) or already in the dictionary (on rename/copy). It is down to the developer to decide how such an error is acted upon.

Helper Function VIPRDVAR

Description Read dictionary information for a File Variable

Parameter Type	Variable Name	Dimension	Length	Description
In	$VariableName		32	Name of the variable to read from the dictionary
Out	$DataType		1	Data type of variable
Out	#MaximumLength		4	Maximum length of data held in variable
Out	#Dimension		4	Dimension (# of entries) of table field
Out	$DisplayCode		12	Default display mask of variable used when displaying the data
Out	$FillCode		3	Fill code
Out	$StandardValidation		32	Special Check or Global Logic name
Out	$HelpMessage		74	Default Help message of the variable when displayed in a screen
Out	$LongPrompt		32	Long prompt for variable
Out	$ShortPrompt		32	Short prompt for variable
Out	$DefaultTag		32	Default Tag Name to use when adding variable as a new object
Out	$ObjectCode		10	Default PROIV Developer object to create when adding variable as a new Screen object
Out	$ExternalDataType		6	Storage type for this variable, if the file is an External type
Out	$ExternalFormat		6	Storage format for this variable, if the file is an External type
Out	$AlternateVariableName		32	Alternate name of the variable, used to map to a table column
Out	$PermitNullData		1	Permit null data when stored on an external database? (Y to allow)
Out	$ErrorMessage		80	Error message

Notes

This Helper returns the standard set of dictionary attributes for the supplied variable.
An error message is returned if the variable is not found in the dictionary.

Helper Function VIPWRVAR

Description Add/Update dictionary information for a File Variable

Parameter Type	Variable Name	Dimension	Length	Description
In	$VariableName		32	Name of the variable to read from the dictionary
In	$DataType		1	Data type of variable
In	#MaximumLength		4	Maximum length of data held in variable
In	#Dimension		4	Dimension (# of entries) of table field
In	$DisplayCode		12	Default display mask of variable used when displaying the data
In	$FillCode		3	Fill code
In	$StandardValidation		8	Special Check or Global Logic name
In	$HelpMessage		74	Default Help message of the variable when displayed in a Screen
In	$LongPrompt		32	Long prompt for variable
In	$ShortPrompt		32	Short prompt for variable
In	$DefaultTag		32	Default Tag Name to use when adding variable as a new object
In	$ExternalDataType		6	Storage type for this variable, if the file is an External type
In	$ExternalFormat		6	Storage format for this variable, if the file is an External type
In	$AlternateVariableName		32	Alternate name of the variable, used to map to a table column
In	$PermitNullData		1	Permit null data when stored on an external database? (Y to allow)
Out	$ErrorMessage		80	Error message

Notes

This Helper Function updates the standard set of dictionary attributes for a specified variable, or if the variable does not exist in the dictionary, it creates a dictionary entry for it with the defined attributes.
The variable name and default tag parameters are mandatory. The default Tag Name must meet the same criteria as in PROIV Developer. For example, it cannot start with a number or contain spaces, and an error is returned if the tag name is invalid.
When updating an existing dictionary variable, it is recommended that this Helper Function is used in conjunction with VIPRDVAR, which can be called to obtain the existing values of the standard attributes. The values can then be altered as required and updated by calling VIPWRVAR. If an attribute has no value assigned to it, that attribute is set to a null string or a zero value when the dictionary variable is updated.
Developers can also call the VIPRDVAR Helper Function to determine if the variable already exists in the dictionary; it returns an error message if it does not exist.
At this time it is not possible to define or change the default object code for the variable. New variables are created in the dictionary with the default type of Edit Box.

Helper Function VIPRNVAR

Description Copy Dictionary information for a new/renamed File Variable.

Parameter Type	Variable Name	Dimension	Length	Description
In	$OriginalVariableName		32	Name of the variable to read from the dictionary
In	$NewVariableName		32	Name of the variable to create in the dictionary
In	$OptionalNewDefaultTag		32	Default Tag Name to use when adding the new/renamed variable as a new object
Out	$ErrorMessage		80	Error message

Notes

The original variable name and the new variable name parameters are mandatory. An error is returned if the original variable does not exist, or if the new variable already exists in the data dictionary.
This Helper Function copies all dictionary information, including any logics, error messages from the original variable name to the new variable name. This is likely to be of most use when copying or renaming File Definitions and their variables via the supplied PROIV Developer file layouts.
At this time it is not possible to define or change the default Object Code for the new variable, it is created with the same Object Type as that of the copied variable.
The default Tag Name for the new variable can be specified or it can be left null, in which case the new variable has the same default tag as the original. If a default Tag Name is specified, it must meet the same criteria as in PROIV Developer. For example, it cannot start with a number or contain spaces, and an error is returned if the Tag Name is invalid.
Specifying the name of default tag in the Rename Process may simplify the copy/rename process in your utility. If the tag is to be altered after the variable has been copied, your utility first reads the standard dictionary values using VIPRDVAR, and then writes them back using VIPWRVAR along with the updated default tag.

Helper Function VIPDLVAR

Description Delete a File Variable from the dictionary

Parameter Type	Variable Name	Dimension	Length	Description
In	$VariableName		32	Name of the variable to read from the dictionary
In	$DeleteVariableEntry		1	When 'Y' remove the variable from the dictionary as well as the object defaults
Out	$ErrorMessage		80	Error message

Notes

· This Helper Function deletes the specified variable from the Data Dictionary and returns an error message if the variable is not found.

· There is an optional input parameter to delete the variable entry from the Data Dictionary. To completely remove the variable and all extended dictionary information for it, the input parameter must be set to ‘Y’.

· If the parameter is left as null, or set to ‘N’, then only the extended Data Dictionary information is deleted, and the Object Code is reverted to Edit Box. The standard set of information, such as the length and help messages are retained.

Description: Description: caution

Caution should be exercised when using the Delete Variable Helper Function as PROIV Developer normally retains entries for all variables used on File Definitions. The permanent deletion of variables which are used on File Definitions could lead to unexpected problems when using PROIV Developer.

Rebuilding File Definitions and Global Logics to Native PROIV

When a File Definition or a Global Logic is altered, it must be built to the native version. There are two Helper Functions supplied to do this, VIPFLBLD for File Definitions and VIPGLBLD for Global Logics.

Both can be called at any time, but it is the responsibility of the developer to check for record locks on the Native versions first.

Helper Function VIPFLBLD

Description Rebuild File Definition

Parameter Type	Variable Name	Dimension	Length	Description
In	$FileName		32	Name of the File Definition to be rebuilt in Native PROIV
Out	$ErrorMessage		80	Error Message

Notes

If the file name is not specified, or if the File Definition does not exist in PROIV Developer, an error message is returned.
If the File Definition has Child Definitions, these are rebuilt so extended lock- checking may be required.

Helper Function VIPGLBLD

Description Rebuild Global Logic

Parameter Type	Variable Name	Dimension	Length	Description
In	$GlobalLogicName		32	Name of the Global Logic to be rebuilt in Native PROIV
Out	$ErrorMessage		80	Error message

Notes

If the Global Logic name is not specified, or if the Global Logic does not exist in PROIV Developer, an error message is returned.

Comment on this topic

Topic ID: 500668