# Views Definition Object

ViewCtl |

ViewCtl is the main interface object. The following alphabetically arranged list of properties and methods belongs to the ViewCtl object:

| AddDataGroup | GetDataSource( ) | RemoveFromDataGroup( )
| AddDataSource( ) | GetDataSourceIDs$( ) | RemoveItem( )
| AddItem( ) | GetGroupID$( ) | RemoveLink( )
| AddLink( ) | GetImportList$( ) | Save( )
| AddView( ) | GetItem( ) | SetCloseLogic( )
| AssignToDataGroup( ) | GetItemCount( ) | SetCondition( )
| ChangeDataGroupDescription( ) | GetLink( ) | SetDescription( )
| CheckDuplicateDescription$( ) | GetNextKeyID$( ) | SetDescription$( )
| Clear( ) | GetType$( ) | SetDirectory( )
| ClearGroups( ) | GetView( ) | SetExecutionLogic( )
| CloseLogic$ | GetViewCount( ) | SetFilter( )
| CloseLogicType$ | Import( ) | SetImport( )
| Copy( ) | InitLogic$ | SetInitLogic( )
| CopyDataGroup( ) | InitLogicType$ | SetInternalKeyCode( )
| DataGroup( ) | InternalKeyCode$ | SetLogicObject( )
| DataSource( ) | List$( ) | SetUnassignedMessage( )
| Delete( ) | ListByGroup$( ) | TranslatePath$( )
| DeleteDataGroup( ) | ListGroupMembers$( ) | UnassignedMessage$
| DeleteFromDataGroup$( ) | ListMemberGroups$( ) | UserLogic
| Disable( ) | Load( ) | VError
| ExecutionLogic$ | LoadDataGroup( ) | VError$( )
| ExecutionLogicType$ | LogicObject$ | ViewDef( )
| Export( ) | OpenLink( ) | ViewMessage$( )
| FindOrphans( ) | Print( ) | ViewsDirectory$( )
| GetDataGroup( ) | Remove( ) | WriteDataGroup( )
| GetDataGroupCount( ) | RemoveDataGroup( ) |

Full descriptions of all ViewCtl Properties and ViewCtl Methods (grouped according to functionality) are provided below.

For descriptions of the different individual objects, see ViewDef, ViewItem, DataGroup, DataSource, DS_Item and DS_Link.

## ViewCtl Properties

The following table lists the properties of the ViewCtl object, as well as groups of subordinate objects:

Property | Description
CloseLogic$ | Logic to be executed prior to exiting the Views System. See Logic Procedures.
CloseLogicType$ | Same as for InitLogicType$.
ExecutionLogic$ | Logic to be executed prior to retrieving data. See Logic Procedures.
ExecutionLogicType$ | Same as for InitLogicType$.
InitLogic$ | Logic to be executed upon entering the Views System. Reference based on InitLogicType$. If type C, InitLogic$ contains program;entrypoint. If type X, InitLogic$ contains PxPlus statement(s) to be executed. String, 128 characters. See Logic Procedures.
InitLogicType$ | Single character string indicating logic type:
C | Call
X | Execute
I or blank | Ignore (Default)
InternalKeyCode$ | Internal key code to be used as the three-character prefix for internal ID values for new views, data sources, items, links and groups. If the given code is not three characters long, it will be left justified and padded on the right with spaces. Default value is 000. Use SetInternalKeyCode( ) method to set.
LogicObject$ | Object specified to supply logic references. See Logic Procedures.
UnassignedMessage$ | Message to be used for the default data group to which views and data sources belonging to no data group are assigned. Use SetUnassignedMessage( ) method to set.
UserLogic | Object identifier for LogicObject$.
VError | Code number indicating the type of error that caused a method to fail. For code details, use the VError$( ) method or see VError Codes.
ViewMessage$ | String to be prefixed to a view description; e.g. "View:".
ViewsDirectory$ | Directory in which to access the Views definition files (pvxview.*). If blank, normal search rules will apply. Read only. Set using SetViewsDirectory( ).
The following are local object Groups (*obj/group) that define lists of related objects:
DataGroup | Standard group list of DataGroup objects. One object for each data group to which the views and data sources in memory belong.
DataSource | Standard group list of DataSource objects, including the primary and related data sources.
ViewDef | Standard group list of ViewDef objects. One object for each view.

## ViewCtl Methods

The tables below group different ViewCtl methods according to their functionality. Use the following links to jump to a particular group of methods:

| Loading and Manipulating Definitions in Memory
| Saving Definitions
| Direct Access to Definition Files (Update Methods)
| Direct Access to Definition Files (Retrieval Methods)
| Export and Import Methods
| Miscellaneous Methods

Loading and Manipulating Definitions in Memory

These load and manipulate the ViewCtl object and its subordinate objects in memory. They do not affect the pvxview.* definition files. To commit any changes to the definition files, invoke the Save( ) method.

Method | Description
AddDataGroup(GrpDesc$) | Create/name new group definition.
AddDataSource(SrcType$, SrcName$[, ExprFlg$ ]) | Create a DataSource object and initialize its properties with information based on the source. Source type indicator:
L | PxPlus file identified by logical name
P | PxPlus file identified by path name or prefix file reference to an external database table (PxPlus SQL ODBC Driver, ADO, Oracle, MySQL or DB2)
O | Custom data source object
T | External database table
SrcName$ will vary depending on SrcType$: logical file name (L), PxPlus file name/path or prefix file reference to an external database table (P), object name;tableID (O), or (T) open string for the database table composed of the database file tag ([ODB], [DB2], [OCI]) followed by DSN; table_name;KEY= KeyDef [; other_connection_strings ]: [ODB]Northwind;Customers;KEY=Custo merID;KEY=CompanyName If the database is located on a WindX client, the [WDX] tag may be prefixed to SrcName$. ExprFlg$ indicates whether SrcName$ contains an expression that must be evaluated. ""(null) indicates that SrcName$ contains fixed value (default) and an "=" indicates an expression to be evaluated. No DS_Item or DS_Link objects are created.
AddItem(SrcObjID | SrcDesc$[, ColName$ | " * " ]) | Add a new DS_Item object to the specified data source. If a column name (no trailing "$") is specified, the object is initialized with information derived from the data source driver. If an *asterisk is supplied, all columns in the source will be added.
AddItem(VuObjID | VuDesc$, ItemPath$) | Add a new ViewItem to the specified view, based on the item path. The sequence of the ViewItem objects will be adjusted automatically to ensure they are grouped by their linkage path.
AddLink(PSrcDesc$, LSrcDesc$, kno$, KeyDef$) AddLink(PSrcObjID, LSrcObjID, kno$, KeyDef$) | Create a new DS_Link object based on the specified parent data source and link source. kno$ is the key number, and KeyDef$ is the Key expression to read the linked data source.
AddView(DS_Desc$ | SrcObjID) | Create a ViewDef object based on the specified data source. If the data source is not currently in memory, it gets loaded.
AssignToDataGroup(Desc$, DataGroup$) AssignToDataGroup(SrcObjID, GrpObjID) | Assign specified view or data source to a data group.
CheckDuplicateDescription$(ObjID, Desc$) | Checks if the description of the view, data source, item, link, or data group has already been used and returns an alternate unused description using a numeric suffix; e.g. Client(2).
Clear( ) | Re-initialize the ViewCtl definition and delete all subordinate objects created by it. (Does not change ViewsDirectory$( ) or InternalKeyCode$.)
Clear(SrcObjID) | Re-initialize the specified ViewDef or DataSource object and delete all subordinate objects.
ClearGroups( ) | Removes all DataGroup objects.
GetDataGroup(GroupDesc$ | idx) | Return the object identifier for the specified DataGroup object.
GetDataGroupCount( ) | Return the number of DataGroup objects.
GetDataSource(DS_Desc$ | idx) | Return the object identifier for the specified DataSource object.
GetDataSourceCount( ) | Return the number of DataSource objects.
GetItem(ObjID, idx) | Return the ViewItem or DS_Item object identifier.
GetItem(SrcObjID, ItemName$ | ItemDesc$) | Return the ViewItem object identifier of the item with the given name or description.
GetItem(VuObjID, ItemPath$ | ColumnName$) | Return the ViewItem object identifier of the view item which has the given path or column name (no trailing "$").
GetItem(ItemPath$) | Return the ViewItem object identifier for the item.
GetItemCount(ObjID) | Return the number of ViewItem or DS_Item objects in the specified ViewDef or DataSource object.
GetLink(SrcObjID, idx) GetLink(SrcObjID, LnkDesc$) GetLink(LinkPath$) | Return the DS_Link object identifier.
GetView(ViewDesc$ | idx) | Return the object identifier for the specified ViewDef object.
GetViewCount( ) | Return the number of ViewDef objects.
Load(Name$) | Create a ViewDef or DataSource object and load it using information from the views definition files. Also creates and loads all related items, links and groups. #### Note: If a view is loaded that has items referencing fields from linked files that do not exist on the system, the items will not be loaded and no error will be generated.
LoadDataGroup(GrpDesc$) | Create a DataGroup object and load with information from the views definition files.
OpenLink(ObjID | LinkPath$) | Load the data source used in the link.
Remove(Name$) | Remove the specified ViewDef or DataSource object and subordinate objects from memory. In the case of DataSource objects, the following are also removed: - Any ViewDef objects using the DataSource as its primary data source. - Any ViewItem objects referencing the data source items. - Any DS_Link objects using the object as its source.
RemoveDataGroup(GrpDesc$ | idx) | Remove the specified DataGroup object from memory.
RemoveFromDataGroup(Desc$, GrpDesc$) RemoveFromDataGroup(SrcObjID, GrpObjID) | Remove the specified view or data source from a data group.
RemoveItem(ObjID, idx) RemoveItem(SrcObjID, ItemDesc$ | ItemName$) RemoveItem(VuObjID, ItemPath$ | ColName$) | Remove a ViewItem or DS_Item object. In the case of removal of a DS_Item object, any ViewItem objects referencing the item will also be removed.
RemoveLink(SrcObjID, LinkDesc$ | idx) | Remove a DS_Link object. Also removes any ViewItem objects referencing the link.
SetCloseLogic(Type$, Logic$) | Set CloseLogic$.
SetCloseLogic(SrcObjID, Type$, Logic$) | Set closing logic for a ViewDef or DataSource object.
SetCondition(VuObjID, ItmPath$, Code, Case [, v1$...v8$]) SetCondition(VuObjID, Column$, Code, Case [, v1$...v8$]) | Set a filter condition at the view item level. ItmPath$/Column$ (no trailing $) - Used to identify the view item.
Code - Condition indicator code:
1 | Equal to <Value1>
2 | Not equal to <Value1>
3 | Less than <Value1>
4 | Greater than <Value1>
5 | Less than or equal to <Value1>
6 | Greater than or equal to <Value1>
7 | Between <Value1> and <Value2> inclusive
8 | Between <Value1> and <Value2> exclusive
9 | Any of <Value1>,<Value1>, …<Value1>
10 | None of <Value1>,<Value1>, …<Value1>
11 | Contains <Value1>
12 | Starts with <Value1>
Case - Case sensitivity indicator: |
0 | Not case sensitive |
1 | Case sensitive |
v1$...v8$ - Values to be used in comparison. Pass numeric values as string arguments. #### Note: View item-level filters are analyzed at run time to optimize data retrieval by determining key ranges for reading records.
SetDescription(ObjID, Description$) | Set the Description$ property of any ViewCtl subordinate object. Checks for duplicate descriptions in the views definition files and in memory. Fails if the description is a duplicate.
SetDescription$(ObjID, Description$) | Set the Description$ property of any ViewCtl subordinate object. Checks for duplicate descriptions in the views definition files and in memory. If the description is a duplicate, a unique description will be created and set using the CheckDuplicateDescription $( ) method. The value of Description$ will be returned.
SetDirectory(Directory$) | Set the directory in which the views definition files are located and open them. Will add a trailing delimiter to the ViewDirectory$ property if omitted. Also clears the ViewCtl object of all subordinate objects.
SetExecutionLogic(Type$, Logic$) | Set ExecutionLogic$.
SetFilter(VuObjID, Condition$) | Set the filter to be applied at the view level.
Condition$ | A free-form PxPlus expression that can be evaluated as true (1) or false (0). Variables used in the condition must be the column names assigned to the view items. The condition may be a simple condition or a complex condition using AND and OR logical operators: CustType$="C" OR CustBalance>1000
#### Note: View-level filters are not analyzed at run time to optimize data retrieval by determining key ranges for reading records. If the filter you are setting could be used for optimization purposes, see if you can set a similar condition at the view item level using the SetCondition( ) method.
SetInitLogic(Type$, Logic$ [, A$ ]) | Set InitLogic$. Set A$ to "A" to apply immediately.
SetInitLogic(SrcObjID, Type$, Logic$) | Set initialization logic for a ViewDef or DataSource object.
SetInternalKeyCode(Code$) | Set the internal key code to be used as the three-character prefix for internal ID values for new views, data sources, items, links and groups. If the given code is not three characters long, it will be left justified and padded on the right with spaces. Default value is 000.
SetLogicObject(ObjID, ObjNm$) | Set logic object for a ViewDef or DataSource object.
SetLogicObject(ObjNm$ [, A$ ]) | Set LogicObject$. Set A$ to A to apply immediately.
SetUnassignedMessage(Message$) | Set the message to be used for the default data group to which views and data sources belonging to no data group are assigned.
TranslatePath$(Path$ [,PathType$]) | Translates an ItemPath$ or LinkPath$ from the descriptive format to the format using object identifiers, used by the ViewDef and ViewItem objects.
Path$ | Descriptive path
PathType$ | Indicates the type of path:
| I or null | Path is an ItemPath$ (Default)
| L | Path is a LinkPath$
Returns a string composed of DS_Link and DS_Item object identifiers. #### Note: This method will open all links (i.e. load the related data sources) used in the path.

LinkPath$ - PrimarySourceDesc$ +SEP [+ LinkDesc$ +SEP...]
ItemPath$ - PrimarySourceDesc$ +SEP [+ LinkDesc$ +SEP...]+ DS_ItemDesc$ (or DS_ItemName$)

Saving Definitions

The Save( ) method commits the definition held in memory by the ViewCtl object to the pvxview.* definition files. It resolves UpdateStamp$ fields, as well as the internal identifiers in memory, for any new objects created using an Add xxx( ) method. (Internal identifiers are the internal keys used by the views definition files.)

Method | Description
Save([ObjID]) | Commit the definition in memory to the views definition files. Save the definition of the specified view, data source or group, as well as any subordinate items, links and groupings. If an object identifier is not specified, save all view and data source definitions in memory, including their subordinate items, links and groupings.
GetNextKeyID$(Channel) | Return the next available internal ID for the specified file (used internally by the Save( ) method).

Direct Access to Definition Files (Update Methods)

The following ViewCtl methods directly update the pvxview.* definition files without affecting any view definitions currently in memory:

Method | Description
ChangeDataGroupDescription(Old$, New$) | Change the description of an existing group.
Old$ | Group description to be changed.
New$ | New description to be assigned.
Copy(Name$, NewName$ [, Group$]) | Copy view or data source definition (header, items and optional group assignments, if Group$ is specified). #### Note: When a view is copied, the password is not copied.
CopyDataGroup(FromGrp$, ToGrp$ [, Flag$]) | Copy members from one data group to another. If the group being copied to does not exist, it will be created.
Flag$ | Indicator to clear members from the receiving group before copying.
"" null | Do not clear the existing group members. (Default)
C | Clear existing group members.
Delete(ViewDesc$ | DS_Desc$) Delete(InternalID$, Type$) | Deletes a view or data source definition. Can also be based on InternalID (i.e. Src_ID$) and Type$ ("D" = Data source, "V" = View). Views: - Header record from pvxview.src - View items from pvxview.vue - Group assignments from pvxview.gpd - Record from providex.ddf Data Sources: - Header record from pvxview.src - Data source elements - Link references - Group assignments from pvxview.gpd - Does not delete views references to data source
DeleteDataGroup(GroupDesc$) | Delete the specified group definition. If any views or data sources are "orphaned" by the deletion of the group, they will be placed in the default or unassigned group.
DeleteFromDataGroup$(GrpDesc$, Desc$) | Delete the specified view or data source from the data group.
Disable(DS_Desc$) | Flag the data source as disabled: Set SRC_TYPE$ field in pvxview.src header to "D" and delete group assignments from pvxview.gpd. Does not remove items or link/view references.
FindOrphans( ) | Find views and data sources that do not belong to a data group and put them in the default data group.
WriteDataGroup(GrpDesc$, SrcList$ [, Flag$]) | Add the views and data sources in the list to the group.
ScrList$ | List of view and data source descriptions separated by SEP
Flag$ | Indicator to clear existing group relationships first
" " null | Do not clear existing group relationships
C | Clear existing group relationships

Direct Access to Definition Files (Retrieval Methods)

The following ViewCtl methods retrieve information directly from the pvxview.* definition files without regard for any view definition currently in memory:

Method | Description
GetDataSourceIDs$(ViewDesc$) | Returns a SEP-separated string containing the internal ID's of all data sources referenced in the view specified by ViewDesc$, or a null string if an error occurs. If the view references a link whose link record is missing, then the ID for the data source associated with the missing link is listed as "00000000".
GetGroupID$(GrpDesc$) | Returns the internal ID (Grp_ID$) of the specified group. Useful for determining if a group exists. Returns "" (null) if the group does not exist.
GetType$(Desc$) | Returns the SourceType$ of the specified view or data source.
List$( ) List$(Type$,[Bmp1$ [Bmp2$]]) | Returns a $00$ separated list of views and/or data sources in alphabetic order. The Type$ indicator will determine what is returned:
A | Views and data sources (Default)
D | Data sources
V | Views
G | Groups
Bitmap references are: Bmp1$ = Bitmap for data source (e.g. "!File" ), or views (e.g. "!Grid" ) if Type$ ="V" Bmp2$ = Bitmap for views (e.g. "!Grid" ) if Type$ ="A" If bitmap references are included, the format for each item in the return value will be: Bmp$+SEP+Description$+$00$ The return value is suitable for display in a List Box.
ListByGroup$([Type$]) ListByGroup$(Type$, B1$, B2$ [, B3$]) ListByGroup$(Type$, B1$, B2$, B3$,"S") | Returns a list of views and/or data sources sorted by data group. The Type$ indicator will determine what is returned:
A | All views and data sources (Default)
D | All data sources
V | All views
Normally, data groups with no items will be suppressed, unless the "S" flag is included. If no bitmap references are included, format of the items will be: DataGroupDesc$+ SEP +View|DataSourceDesc$+ $00$. Bitmap references are: B1$ = Bitmap for the group level (e.g. "{!Files}" ) B2$ = Bitmap for data sources (e.g. "{!File}" ) or views if Type$ ="V" B3$ = Bitmap for views (e.g. "{!Grid}" ) if Type$ ="A" Format of each item in the return value with bitmaps: Bmp$ + GrpDesc$ + SEP + View|DataSourceDesc$ + $00$. The return value is suitable for display in a Tree view control.
ListGroupMembers$(GrpDesc$ [,[LB_Type$]) ListGroupMembers$(D$, LBT$, B1$, B2$, B3$) | Returns a list of views and data sources which belong to the specified group. The LB_Type$ indicator determines how the output will be formatted:
L | Formatted for List Boxes (Default)
T | Formatted for Tree View controls
If no bitmap references are included, the format of individual items in the return value will be:
List Box: | View | DataSourceDesc$ + $00$
Tree View: | DataGroupDesc$ + SEP + View | DataSourceDesc$ + $00$
Bitmap references are: B1$ = Bitmap for the group level (e.g. "!Files" for List Boxes and "{!Files}" for Tree Views) B2$ = Bitmap for data sources (e.g. "!File" for List Boxes and "{!File}" for Tree Views) B3$ = Bitmap for views (e.g. "!Grid" for List Boxes and "{!Grid}" for Tree Views) Format of each item in the return value with bitmaps:
List Box: | B2$ | B3$ + View | DataSourceDesc$ + $00$
Tree View: | First entry: B1$ + GrpDesc$ + $00$ Other entries: B2$ | B3$ + GrpDesc$ + SEP + Desc$ + $00$
ListMemberGroups$(MemberDesc$) | Return a SEP-separated list of groups to which a specified data source or view belongs.
Print(Type$ [, Desc$ [,"V"][, Opt$]]) | Print view and/or data source definitions to the printer or PxPlus Viewer. If the outputting to the printer, "*winprt*;Asis" is used to output directly to the Windows default printer without invoking the printer dialogue box. Type$ will determine what type of definition is printed:
A | Data sources and views |
D | Data sources |
V | Views |
G | Groups |
Desc$ | Determines which definition is printed. If omitted or "" null, all definitions of the specified type are output.
V | Outputs to the PxPlus Viewer rather than to the printer. If omitted, the default destination is the Windows default printer.
Opt$ | Provides printer options: Normal, Asis (Default) and Default.

Export and Import Methods

ViewCtl export and import processing is accomplished using the methods described in the following table:

Method | Description
Export(Channel [, SourceList$]) | Export the specified definitions to a specially formatted text file. Channel is the open channel to the serial file to which the exported definitions will be written. SourceList$ provides a list of data sources and views to be included in the export file. List entries are separated by $00$. If SourceList$ is omitted or blank, the default is to include all definitions. The application must open/close the export text file, as well as purge it, if desired. When exporting, the text file must also be locked, unless the 'LU' parameter is set.
The following methods handle importing definitions:
GetImportList$(Channel [, Code$]) | Return a SEP-separated list of the data sources and views included in the exported file. The optional code will determine what source types will be included in the list:
A | All (Default); i.e. data sources and views
D | Data sources only
V | Views only
SetImport(SrcDesc$, MergeOpt) | Specify a definition to be imported (must exist in the exported file). (Used in conjunction with Import( )). SrcDesc$ is the data source or view description to be imported (must exist in the exported file). MergeOpt provides options for dealing with definitions that exist in both source/destination files, as follows:
0 | Skip the definition
1 | Replace the contents of the destination definition with those of the source
2 | Merge the contents of the two definitions, with precedence given to the source
Import(Channel) | Import the data source and view definitions specified previously using the SetImport( ) method, or all the definitions if none have been specified by SetImport( ). In the latter case, merge option 1 (replace) will be used. Channel is the open channel to an exported file.

Miscellaneous Methods

Other ViewCtl methods are described as follows:

Method | Description
VError$([ErrorCode]) | Return a description of the last view error to occur (based on the contents of the VError property) or of the specified ErrorCode. See VError Codes. The format of the error description is as follows: Views Error #nnnn - ClassName: Method( ) Error Description Example: Views Error #1234 - ViewCtl: GetView( ) View not found