Programs and Utilities – Page 11 – 4GL APPLICATION FRAMEWORK

ZOMExport

Exports the dictionary descriptions of selected objects to documents.

Syntax

ZOMExport object specification [option…]

Options

;k [!]

The ;k option is used to assign a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the selected object(s).

;p [!]

Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).

The ;f option specifies the format that the Object Dictionary specifications are to be exported in. There are several available formats:

Z50	To export in Z50 format, omit the ;f option. This is the default import/export format, and is recommended for exchanging definitions between ZOM enabled environments. File names for Z50 files end in “.z50”.
Z41	This produces output compatible with ZOM export/import files created by versions of ZOM prior to Version 5.0. This format is useful for exporting definitions into Zim environments where earlier versions are in use. File names for Z41 files end in “.z41”.
DT4	This produces output compatible with ZimSAVE and ZimLOAD. It is useful for exchanging objects between ZOM and older versions of Zim. File names for DT4 files end in “.dt4”.
OEF	This produces output compatible with the Object Exchange Format, a generic object exchange format definition designed for integration with other development tools. File names for OEF files end in “.oef”.

Normally ZOMExport clears the Shadow Dictionary before adding the objects selected from the Object Dictionary. The ;a option forces ZOMExport to skip clearing the Shadow Dictionary so that the selected objects are appended to those already in the shadow.

;t sh

Export the objects from the Shadow Object Dictionary, rather than the Object Dictionary.

Comments

ZOMExport starts by clearing the Shadow Dictionary unless the ;a option has been specified. It then selects objects (using

Examples

The following command exports the object named “Customers.” It is exported in Z50 format.

ZOMExport Customers

The following command exports the objects keyworded by the keyword “To_Export.” The objects are exported in DT4 format.

ZOMExport +k To_Export ;f DT4

ZOMErase

Erases selected objects (but does not delete any dictionary or object descriptions).

Syntax

ZOMErase object specification [option…]

Options

;k [!]	Assigns a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the selected object(s).
;p [!]	Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).

Comments

This erases the actual Zim objects specified, but not delete the object’s definitions in the application dictionary.It is important to differentiate among erasing an object, deleting an object, and destroying an object. Erasing an object undoes the act of creating an object. Creation takes a Object Dictionary description and uses it as the basis for constructing a system representation of the object in the indicated directory. Thereafter, the object can be used. Erasing an object erases this system representation, but still leaves the Object Dictionary description intact. Deleting an object deletes the object’s description from the Object Dictionary, but leaves its system representation intact. Destroying executes both an erase and a deletion, as well as deleting the registration information from the Object Dictionary. An object can be erased and deleted without being destroyed, if the ZOMErase and ZOMDelete functions are executed separately.This command checks the set of objects to be processed for locked objects prior to executing. If there are locked objects to be processed, the command issues an error and exits. An object is considered to be locked if it is locked itself, or is in a locked directory. For information about setting and clearing locks, refer to ZOMSet.This command touches the objects erased once its action has completed. This results in the object’s status and dependency information being updated. This operation can also potentially affect the status of programs and objects which depend on the erased objects. If ZOM is configured with its Explode Level to be 1, then this command finds the dependent objects and touches them. For more information, refer to ZOMTouch and the discussion of dependencies in Object Dependencies.This action results in the objects affected being keyworded as “changed.” The exact keyword used is determined by ZOM’s configuration. For more information, refer to ZOMConfig.

Examples

The following command erases the object named “Customers.” It is erased from the database environment, but its description in the Object Dictionary is retained.

ZOMErase Customers

The following command erases the objects keyworded by the keyword “To_Erase.”

ZOMErase +k To_Erase

ZOMExec

Execute a user query against selected objects.

Syntax

ZOMExec object specification [option…]

Options

;k [!]	The ;k option is used to assign a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the object(s).
;p [!]	Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).
;d	This specifies that the output is to be written to the indicated document. The document must be already created. If the ;d option is omitted, it indicates that the output is to be written to the screen.
;a	If a document name is specified, the ;a option indicates that the output is to be appended to the end of the document. If the ;a option is omitted, it indicates that the output is to replace the contents of the document specified in ;d option.
;b	If a document name is specified, the ;b option indicates that you would like to browse the document file after the action is completed. The ;b option does not take effect if the ;d option was not used to specify an output document.
;w	If a document name was not specified, the ;w option sets pause on while the information is being listed to the screen. The ;w option does not take effect if output is directed to a document using the ;d option.
;q	The name of a query program created using the DPSMakeQuery command.

Comments

ZOMExec executes the specified query for each of the objects selected. The query must be created using the DPSMakeQuery command. Information on the current object being processed by ZOMExec is provided to the query program in a collection of pre-defined variables:

vObjectName	The name of the object.
vObjectDirName	The name of the Zim directory containing the object.
vObjectOwnerName	The name of the owning object.
vObjectKey	The object’s unique identifier key.
vObjectType	The type of the object.
vObjectActive	The active property; “Y” indicates active.
vObjectLocked	The locked property; “Y” indicates locked; “D” indicates the Zim directory is locked.

Example

The following command executes the query “Change_Colors” for each object of type Form.

ZOMExec +t Form ;q Change_Colors

ZOMDataLoad

Imports records into a table from a document.

Syntax

ZOMDataLoad object specification [option…]

Options

;k [!]	The ;k option is used to assign a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the object(s).
;p [!]	Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).
;d	This is the name of the document (which must already exist) from which data is loaded. This document should have been previously specified as the ;d option in a ZOMDataSave command for the same object.If you specify a specific document, it is recommended that you execute the data load against one object, since the document is defined to save data from a single specific object.If you do not specify a document name, ZOMDataLoad uses the internal data save document name associated with each object.
;r	This service generates a program that executes the data load function. This program is normally put in a temporary document. By specifying the name of the document to be used to store the program, ZOMDataLoad reroutes the program code to this document instead.
;q	This option causes ZOMDataLoad to skip actually loading the data. The programs to load data are created.

Comments

This program can be used to restore temporarily saved data into the object. The data usually comes from the internal ZOM document associated with each object that contains data. If, however, a ZOMDataSave was done where the data was saved into a named document, then that data can be loaded by specifying the document name with the ;d option.The ;r option can be used to also generate a program that actually carries out the load operation. This program could be incorporated directly into your application where it may be necessary to load data into an object.The data which ZOMDataLoad can retrieve must be created using ZOMDataSave.

Examples

The following command loads the contents of the EntitySet “Customers” from the datasave document associated with the Customers object.

ZOMDataLoad Customers

The following command loads the contents of the EntitySet “Customers” from the document “dsCusts.” The program that executes the data load is generated into the document “pCustDataLoad.”

ZOMDataLoad Customers ;d dsCusts ;r pCustDataLoad

As long as the definition of Customers does not change, subsequent data loads can be accomplished by executing the generated program, as shown below. This program can be compiled and embedded in your shipping applications.

pCustDataLoad()

The following command loads the data in all objects with the DataSave property set (i.e., EntitySets and relationships with fields). The data in these objects must have been previously saved using ZOMDataSave.

ZOMDataLoad +p ds

ZOMPermBoot

Generates a program to set user access permissions.

Syntax

ZOMPermBoot object specification [option…]

Options

;k [!]	Assigns a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the object(s).
;p [!]	Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).
;d	Specifies that the output is to be written to the indicated document. The document must be already created. If the ;d option is omitted, it indicates that the output is to be written to the screen.
;o [r] [a] [c\|u] [d]	Indicates the permissions to set for the owner of the object. “r” represents “read” privilege, “a” represents “add” privilege, “c” (or optionally “u”) represents “change” or “update” privilege, and “d” represents “delete” privileges.
;g [r] [a] [c\|u] [d]	Indicates the permissions to set for members of the same group as the owner of the object. “r” represents “read” privilege, “a” represents “add” privilege, “c” (or optionally “u”) represents “change” or “update” privilege, and “d” represents “delete” privileges.
;t [r] [a] [c\|u] [d]	Indicates the permissions to set for users other than the owner or member of the same group for the object. “r” represents “read” privilege, “a” represents “add” privilege, “c” (or optionally “u”) represents “change” or “update” privilege, and “d” represents “delete” privileges.
;a	If a document name is specified, the ;a option indicates that the output is to be appended to the end of the document. If the ;a option is omitted, it indicates that the output is to replace the contents of the document specified in ;d option.
;b	If a document name is specified, the ;b option indicates that you would like to browse the document file after the action is completed. The ;b option does not take effect if the ;d option was not used to specify an output document.
;w	If a document name was not specified, the ;w option sets pause on while the information is being listed to the screen. The ;w option does not take effect if output is directed to a document using the ;d option.

Comments

This generates a program consisting of permission statements which set the permissions for the objects indicated as specified in the option list. It is used to generate system bootstrap scripts.

Examples

The following command generates a program that, when executed, sets the permissions on the object “Customers” such that the owner, group and others all have full access privileges. The output is written to the document “SetCustPerms.”

ZOMPermBoot Customers ;o racd ;g racd ;t racd ;d SetCustPerms

The following command generates a program that, when executed, sets the permissions on the object “Customers” such that the owner, has full access, and the group and others all have read access privileges. The output is written to the document “SetCustPerms.”

ZOMPermBoot Customers ;o racd ;g r ;t r ;d SetCustPerms

ZOMDataSave

Exports records from selected tables into documents.

Syntax

ZOMDataSave object_specification [option…]

Options

;k [!]	The ;k option is used to assign a keyword to the selected object(s). If the keyword is already assigned, this assignment is ignored. If “!” is specified, the keyword assignment is removed for the object(s).
;p [!]	Set the specified user-designated property for the selected object(s). If “!” is indicated, the specified property is reset for the selected object(s).
;d	This is the name of the document to be used to store the data that is saved. The document does not need to exist prior to invoking data save.The document is (re)created with field definitions that make it suitable for saving data stored in the table.If you specify a specific document, you should execute the data save against one object, since the document contains only data from the last saved object after the command has executed.If you do not specify a document, ZOM creates a special internal document for each object.
;f	If you specify the document used to store the data and the document does not exist, you must specify the filename to be used by the document. This can be omitted if the data save document already exists.
;r	This option generates a program that executes the data save function. This program is normally put in a temporary document. By specifying the name of the document to be used to store the program, ZOMDataSave reroutes the program code to this document instead.
;q	This option causes ZOMDataSave to skip actually saving the data. Datasave documents and the programs to save data in those documents are created.

Comments

ZOMDataSave can be used to save data (including null values) in objects that can contain data (e.g. an EntitySet or relationship). The data is saved in a document that has special fields defined by ZOM. This document is (re)created every time ZOMDataSave is executed for an object. If you do not specify a document name as a parameter, ZOM generates a document name for you and internally associates this document name with the object.The ;r option can be used to also generate a program that actually carries out the save operation. This program could be incorporated directly into your application where it could be necessary to temporarily save data in an object.Reload the data into the object by using ZOMDataLoad.

Examples

The following command saves the contents of the EntitySet “Customers” to an ASCII file.

ZOMDataSave Customers

The following command saves the contents of the EntitySet “Customers” to the document “dsCusts.” The filename of the document is “custs.ds.” The program that executes the data save is generated into the document “pCustDataSave.”

ZOMDataSave Customers ;d dsCusts ;f custs.ds ;r pCustDataSave

As long as the definition of Customers does not change, subsequent data saves can be accomplished by executing the generated program, as shown below. This program can be compiled and embedded in your shipping applications.

pCustDataSave()

The following command saves the data in all objects with the datasave property set (i.e., EntitySets and relationships with fields).

ZOMDataSave +p ds

The following command makes sure that all objects with the datasave property have associated datasave documents so that, in subsequent ZOMCreate, ZOMReCreate, ZOMErase, and ZOMMove commands, the data is preserved. The data is not actually saved at this point.

ZOMDataSave +p ds ;q

ZOM Commands

The following ZOM commands are available in Zim Object Manager:

ZOMDiff

Compares the object descriptions in the Object Dictionary with object descriptions that have been imported from elsewhere.

Syntax

ZOMDiff […]

Options

;sh	Treat the Shadow Dictionary as the baseline for comparing objects.
;r!	Do not recompute the status of the differences. Issue the report assuming the results to be current.
;d	This specifies that the output is to be written to the indicated document. The document must be already created. If the ;d option is omitted, it indicates that the output is to be written to the screen.
;a	If a document name is specified, the ;a option indicates that the output is to be appended to the end of the document. If the ;a option is omitted, it indicates that the output is to replace the contents of the document specified in ;d option.
;b	If a document name is specified, the ;b option indicates that you would like to browse the document file after the action is completed. The ;b option does not take effect if the ;d option was not used to specify an output document.
;w	If a document name was not specified, the ;w option sets pause on while the information is being listed to the screen. The ;w option does not take effect if output is directed to a document using the ;d option.

Comments

This service compares the contents of the standard Object Dictionary and the Shadow Object Dictionary and reports on how they differ. By default, the Object Dictionary is assumed to be the baseline for comparison, but this can be reversed by using the ‘;sh’ option. A sample report is shown below:

Zim Object Manager

Object Dictionary Differences Report

***Changed Objects in the Dictionary

Document _$Customers zim

Variable i zim

***New Objects in the Dictionary

Directory TestDir Zim

Document diffout Zim

***Deleted Objects from the Dictionary

Variable c1 zim

***Renamed Objects in the Dictionary

Role csts Customers zim (was called: custs)

***Moved Objects in the Dictionary

Document diagout TestDir (was in: Zim)

Document infoout TestDir (was in: Zim)

New objects are defined as objects which exist in the actual dictionary that do not exist in the Shadow Dictionary. Changed objects are defined as objects which have had some of their characteristics changed. For example, a variable whose size has changed. Renamed objects are defined as objects which have matching object keys, but are have different object names. Moved objects are defined as objects which have matching object keys, but are defined to be in different Zim directories.

Example

The following command lists the difference report to the screen with pause mode on.

ZOMDiff ;w

The following command puts the difference report in the document “DiffRpt,” and brings up the document browser on the report.

ZOMDiff ;d DiffRpt ;b

ZOMConfig

Enables user to alter the configuration of the ZOM services.

Syntax

ZOMConfig

Comments

This command brings up an option screen which enables the configuration of ZOM to be edited. ZOM configurations are stored in the registry. The options are

Display Mode	When this option is set to Window, the ZOM status window is displayed while ZOM utilities are being executed. If set to Serial, ZOM status information is displayed a line at a time. If set to None, no status information is displayed.
Error Logging	When this option is turned on, ZOM maintains an activity log file as it executes its actions, including the relevant sections of the errors.trc file. It can slow ZOM operations as the log file grows. You can either turn the option off or regularly clear the errors.trc file by executing the commands: set output errtrace set output terminal
Dependency Trace	ZOM maintains an online cross-reference of the dependencies among the objects in your application. This enables many of the powerful features of ZOM, but requires a reasonably large amount of disk space, and slows ZOM operations. Turning off the dependency tracing option saves disk space and speeds ZOM, but disables explosion and implosion operations, and disables ZOM’s display of cross reference information. Note: If you have been running with dependency information turned off, and then decide to turn it on, the dependency information is not automatically loaded for all objects at that time. You must turn dependency on, and then touch all the objects to be certain that the dependency database is up to date, using the following command: ZOMTouch *
Default Zim Directory	ZOM requires that all objects be assigned an explicit DirName. This is done by actually putting a value in the DirName field for the object, rather than leaving it $null or blank. If ZOM encounters blank or $null DirNames, it uses this value as the DirName, and puts the dirname in the Object Dictionary on your behalf.
Conventions On	If ZOM Conventions are on, ZOM sets two properties on your behalf if certain conditions are met: If an object is has the Data property set, the DataSave property is set automatically. If an object is compiled, the Compilable property is set automatically.
Explode Level	The explosion level determines the extent of actions ZOM undertakes automatically on your behalf on objects which depend on objects you directly manipulate. For example, if you destroy the EntitySet Employees, what should ZOM do to the Relationships and Roles which depend on Employees for their existence? Explode level can be set to either 0 or 1. Explosion level 0 defeats all dependency actions. Explosion level 1 touches objects that depend on objects which are recreated, renamed, moved, erased or destroyed. Explode levels greater than 0 rely on dependency tracking to be on in order to work.
New Keyword	This is a keyword assigned to all newly registered objects. It is a convenient way to keep track of which objects are new to your environment since you last reset this keyword. Throughout this document, this keyword is assumed to be the value “$new”. To reset the keyword so no objects are flagged as new, enter ZOMSet +k $new ;k! $new
Changed Keyword	This is a keyword that is assigned to all objects which have an action applied to them which implies they have been changed in some way. These actions include such commands as ZOMCreate, ZOMReCreate, ZOMReName, ZOMMove, ZOMErase, ZOMDelete, ZOMCompile and ZOMUnCompile. It is a convenient way to keep track of which objects have been manipulated in your environment since you last reset this keyword. Throughout this document, this keyword is assumed to be the value “$changed”. To reset the keyword so no objects are flagged as changed, enter ZOMSet +k $changed ;k! $changed
Environment Code	The Environment Code is used to co-ordinate multiple development environments in a team context. Refer to Team Development Projects and ZOM for more information about the environment code. If you are not coordinating programming teams or working at more than one development site, this field can be left blank. ZOM randomizes an environment code for you.
Express Mode	Certain operations such as ZOMExport can operate in either a set-oriented fashion (express mode is on) or a record-at-a-time fashion. In the former, the command performs more quickly. However, you do not see a separate status displayed for each object as it is processed nor is a separate log entry made for each object. This information is available when express mode is off.

ZOMDiagnose

Report on any improper or unusual object descriptions in the Object Dictionary.

Syntax

ZOMDiagnose […]

Options

;d	This specifies that the output is to be written to the indicated document. The document must be already created. If the ;d option is omitted, it indicates that the output is to be written to the screen.
;a	If a document name is specified, the ;a option indicates that the output is to be appended to the end of the document. If the ;a option is omitted, it indicates that the output is to replace the contents of the document specified in ;d option.
;b	If a document name is specified, the ;b option indicates that you would like to browse the document file after the action is completed. The ;b option does not take effect if the ;d option was not used to specify an output document.
;w	If a document name was not specified, the ;w option sets pause on while the information is being listed to the screen. The ;w option does not take effect if output is directed to a document using the ;d option.

Comments

This service examines the object descriptions in the Object Dictionary and report any unusual conditions. Sample output is shown below:

ZOM Diagnose Report

********************************************************

*** Documents duplicating filenames of other documents
********************************************************

DirName DocName

Zim halt $console

Zim terminal $console

Zim start zimprof

Zim zimprof zimprof

********************************************************

*** Non unique use of Field SNs within OwnerName

********************************************************

DirName OwnerName FieldName SN

zim Customers IndType 100

zim Customers Name 100

zim FilledBy Amount 100

zim FilledBy UKFilledBy 100

zim Require Amount 100

zim Require UKRequire 100

********************************************************

*** Fields without Owners

********************************************************

DirName OwnerName FieldName

Zim Testent Field1

********************************************************

*** Dfs without Displays

********************************************************

DirName DisplayName FormDirName FormName

Zim testdisp zim xxxxxxxx

********************************************************

*** Dfs without Forms

********************************************************

DirName DisplayName FormDirName FormName

Zim testdisp zim xxxxxxxx

Examples

The following command lists the diagnosis report to the screen with pause mode on.

ZOMDiagnose ;w

The following command puts the diagnosis report in the document “DiagRpt,” and brings up the document browser on the report.

ZOMDiagnose ;d DiagRpt ;b