Views Definition Object

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:

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.

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.

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.

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.

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).

Method

Description

ChangeDataGroupDescription(Old$, New$)

Change the description of an existing group.

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.

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.

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:

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:

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:

If no bitmap references are included, the format of individual items in the return value will be:

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:

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:

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:

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:

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.

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