| Contents: | Main | Chapter | See Also: | Getting Started Manual | Advanced User Manual | |||
The PACKAGE file (#9.4) is used both to document a software package and to aid in exporting the package. A PACKAGE file entry is not required to build inits; inits can be built on the fly. Some of the fields are used for documentation only and some for both the export process and documentation. Whenever you build an init using an entry in the PACKAGE file, that entry is also put into the PACKAGE file of the target system when the init is run. Thus, a copy of the documentation for the package will be on both the source and target systems.
The fields that DIFROM uses during the package export process are described below. All fields not noted below are used for documentation only:
This is a brief (4-30 characters) name describing the package. It is used to identify the package and does not affect the init directly. However, it is the key field used when installing the PACKAGE file entry on the target system. If you change the name and install a package on a system where it already exists under a different name, a new entry will be created in the PACKAGE file on the target system. The unchanged old entry will remain, too.
This is the 2-4 character namespace of the package. It is the unique identifier for the package. The PREFIX controls which Templates, Options, Bulletins, etc., are included in the init routines for export. Those components with names beginning with the package's PREFIX are automatically exported, except for those beginning with the letters in the EXCLUDED NAME SPACE multiple.
There is a multiple field for each of the following template types: INPUT, SORT, PRINT, and SCREEN (FORM). The developer uses these multiples to have the init include templates in addition to those within the PREFIX namespace. Each of these multiples contains the free-text name of a template and the number of the file associated with that template (a pointer to the FILE of Files).
Note that for SCREEN (FORM) templates, all blocks pointed-to by exported forms are automatically included in the init regardless of their namespace. The blocks need not be specified by the developer.
The developer can use the EXCLUDED NAME SPACE multiple to exclude templates, options, bulletins, etc., that are a subset of the package's namespace. For example, if the namespace of a package were PRC and the EXCLUDED NAME SPACE multiple contained the entry PRCZ, then any of the components of the package with names beginning with "PRCZ" would not be exported.
When the installer starts the init, the routine identified in the ENVIRONMENT CHECK ROUTINE field is run before any of the init routines DIFROM created and before any questions are asked. The installer cannot interrupt the init process until this routine has completed. Thus, this pre-init should be used to simply examine the environment; it should not change any data.
The routine named in the PRE-INIT AFTER USER COMMIT field runs after the installer has committed to proceeding with the install but before any data is updated. This routine may edit or delete data. The developer uses this routine to make any data conversions, etc., that need to be performed before the init brings in new data.
The routine named in the POST-INITIALIZATION ROUTINE field runs after the inits put everything in place. Here, the developer makes any data conversions, etc., that need to be performed after the new data is installed.
This is a multiple field used to describe how the data dictionaries (DDs) and data from the exported files are to be handled in the inits. The following fields are included within the FILE multiple:
This field contains the number of the file to be exported. It is a pointer to the FILE of Files (#1).
This optional multiple within the FILE multiple allows the developer to send a subset of the fields from a file. If only some of the fields are being exported, a "partial" file is being sent. If no entries are made in the FIELD multiple, all of the fields from the file are exported. Only the names of fields at the top level of a file can be entered. Thus, single fields at the top level and entire multiples with all the subfields and subfiles descendent from those multiples can be sent.
The .01 field will automatically be sent, whether or not it appears in this multiple, unless the file being exported is File #200. If a partial of File #200 is being sent, the .01 is sent only if it is included in this multiple or if the PREFIX is XU (Kernel's namespace).
NOTE: This list only applies to the information about fields found in the data dictionary. It is not possible at this time to send a subset of the actual data.
If this set of codes field is YES, the version number entered by the developer while running DIFROM to build the init will be used to create the following node when the init is run on the target system:
^DD(File#,0,"VR")=Version Number
The version number is that of the package being installed, not the VA FileMan version number.
If this field is NO or left null, a "VR" node will not be built by the init. Thus, whatever was present in this node on the target system will remain. Once a "VR" node has been set, the developer should continue to update it with each version. Otherwise, the node will contain the wrong version.
This set of codes field controls whether or not a pre-existing DD on the target system will be updated during the init. The DD is included in the init routines regardless of how this question is answered. If a DD for the file does not exist on the target system, it is always installed.
If this field is YES or left null, the DD in the init will overlay an existing DD on the target system.
NOTE: The existing DD on the target system is not deleted first. For example, if a field is changed from one type to another, it is possible that the DD information from the previous definition of the field will be left behind. This situation may cause problems for FileMan. If this might happen, the developer is urged to clean up the field from the DD in a pre-init, using a call to ^DIK.
If this field is NO, the DD currently on the target system will not be changed. The developer can still send data for the file.
If this set of codes field is YES, the installer decides if a pre-existing DD will be overwritten. When the init routine runs, the question, "Shall I write over the existing Data Definition?" is asked if there is a pre-existing DD on the target system. If the installer answers this question NO, the existing DD will not be changed. This feature is useful when a package contains some DDs that are unchanged from the previous version. If the DD is not found on the target system, it will be brought in by the init regardless of this field's contents.
If answered NO or left null, the installer cannot choose whether or not to not bring in the DD.
NOTE: If there is a screen on the DD, the question is not asked regardless of the contents of this field. The result of the screen's test determines if the new DD is installed or not.
The developer can enter M code in this field to examine the target environment to determine whether or not to bring in a DD. The code should set the value of $T. If $T is true, the new DD is installed; if $T=0, it is not. If the developer enters a screen, the installer is not given the option of installing the DD. The screen alone determines whether or not the DD is installed.
NOTE: If the DD does not exist on the target system, the screen is ignored and the incoming DD is installed.
If this set of codes field is YES, DIFROM picks up ALL of the data for the file from the system on which the developer builds the init. This data is included in the init routines. Data from all fields is sent even if the developer is only sending selected fields from the DD. Pointers are not resolved to their external values. Thus, data with pointers should not be sent if the pointed-to entries may be in different locations on the target system.
If this field is NO or left null, the init does not pick up data. The contents of the following two fields are ignored.
This set of codes field controls how exported entries are combined with existing ones on the target site. The possible values are "m" (MERGE) and "o" (OVERWRITE). The default is MERGE.
When an init is installed, incoming entries and subentries are checked to see if they match ones on the target system. (A detailed description of this process is given in the "Running an Init" section.) If a match is not found, the entry or subentry is added. The contents of this field determine what happens to entries that do match.
If incoming entries are to be merged with existing ones, fields with non-null values are left unchanged on the target system. Data from the init is placed into fields with null values.
If incoming entries are to overwrite existing ones, fields with non-null values in the init overwrite values currently on the target system. If the field is null in the init and the field on the target system contains data, the current value is not overwritten with a null value.
If this set of codes field is YES, the installer can decide whether or not to install the data from the init. The installer can choose to bring in the data or not to bring it in. However, the merge/overwrite flag cannot be changed; merge cannot be switched to overwrite, and vice versa.
If the field is NO or left null, the installer cannot choose if the target system's data is updated or not.
Other PACKAGE file fields are used only for documentation and do not affect the DIFROM procedure. One of the documentation fields, SHORT DESCRIPTION, is required. It is a free text field of up to 60 characters. Other documentation fields include: ROUTINE, GLOBAL, VERSION, DEVELOPMENT ISC, and KEY VARIABLE. There are fields to document the development, verification, site installation, and patch history. This data describing the package is bundled and exported with the rest of the package. It is put into the recipient's PACKAGE file.
Some of the documentation fields are updated on the target system when the init is run. For example, the date/time that the pre- and post-inits are run is automatically recorded in the PACKAGE file entry as is the version number.
Reviewed/Updated: March 4, 2007