Section 2: Conversion Hints & APPX Programming Suggestions
Conversion Hints & APPX Programming Suggestions
Item 2.1
In APPX, avoid making changes in the DATA MODIFICATION phase of ADD mode. Call the target back up in CHANGE mode instead.
Item 2.2
Consider exiting and reentering APPX to be sure that critical changes are effective or to flush memory.
Item 2.3
In APPX, when critical changes are needed or as a last resort for problems, consider deleting and re-adding or copying and re-adding (using Design Transfer to copy back items as needed). APPX has many hidden fields that sometimes are not reset properly when certain critical data is changed.
Also, it may be wise not to rename processes. For example, this has been suspected to have caused some problems at Pinellas. They sometimes use Design Transfer to copy a process to another name to work on, leaving the live process under the original name. Then, when they want to activate the work process, rather than renaming, they do the following:
- use Design Transfer to copy the live process to an interim name
- delete the live process
- use Design Transfer to copy the work process to the live name
- when appropriate, delete the work process and the interim process
When using Design Transfer to copy multi-level processes or jobs that you intend to run under the new name, be careful to consider all process names imbedded within, such as on children or job steps or Use Query specifications.
Item 2.4
In APPX, use Option 88 to access the full value of abbreviated fields such as default values and edit masks.
Item 2.5
In APPX, process the data dictionary more than once following critical events such as conversion or sweeping changes. If cross-application references exist, process the data dictionary for each application in series more than once.
Item 2.6
Do not rely too heavily on the APPX Cross-Reference Utility since it often does not find all references and is sometimes inconsistent in what it does find (see item 1.3). It is probably best to use both the APPX X-Ref and the SP2 X-Ref in combination. The SP2 X-Ref is reliable (with the exception that it mislabels built-in functions) but the function name may not always reflect the APPX process name and there is no visibility of references to or in APPX Inquiry processes. Remember a SP2 multi-level process is split into multiple processes in APPX and a SP2 Output can spawn both an Output & Inquiry in APPX if it is used on an INQUIRY job step in SP2.
Item 2.7
When all else fails (provided you have the proper registration), consider accessing the APPX application 0AD (Application Design) to decipher or resolve problems. Enter Application Design for the desired application and then:
99) Invoke a Process
App/Version 0AD 00 Application Design
Database ID
Process Type MENU
Process Name FILES EDIT
Warning: This facility should be used with great caution since there is no editing to preserve the integrity of the design files.
Item 2.8
In order to address conversion problems, it is very helpful to run and save SP2 Tech Doc, X-Ref, etc., on disk so they can be searched as needed using DL or DISPLAY. SP2 documentation is reliable except that the SP2 'Built In Function' X-Ref mislabels the name of the built-in function. Also, for field tech doc, specify 'Fields (By Name)' since 'Fields (By File)' can cause a disk full error or too many extents. To conserve disk space, use Space-Saver to release space from the libraries containing the saved documentation. (See 2.8 attachment for details.)
Selected SP2 documentation should be printed such as the SP2 Table of Contents found at the end of SP2 Tech Doc. It helps to use the SP2 Table of Contents as your bible to the application by marking pertinent facts or unusual conditions on it. This is also a good place to mark functions that need testing.
From the user installation, obtain printouts of all SP2 Installation Control lists and reports as well as SP2 'Edit File Specifications' and 'Display File Information' for all companies. Mark any files that are shared by any company on the SP2 Table of Contents.
By the way, when you want to search for something in SP2 Tech Doc from a specific point, say, starting at input functions, the easiest way is to see what page inputs begin on from the SP2 Table of Contents; then, search for "- nnn" where nnn is 1 less than the beginning page.
Item 2.9
After importing applications into APPX, it is very helpful to run and print selected APPX Tech Doc & X-Ref so they are at hand when needed. Remember only the APPX ILF X-Ref may be totally reliable (see items 1.3 & 2.6). (See 2.9 attachment for details.)
Now that the application is in APPX you can mark other pertinent information on your SP2 Table of Contents. The V05 conversion log warns whenever lower level processes are created in the conversion so you could easily mark multi-level processes. The V05 conversion log for Inquiry Functions warns whenever SP2 outputs are converted to APPX inquiry processes or to both APPX inquiry/output processes. (See item 13.2.)
Item 2.10
Before beginning conversion, review the conversion logs and the SP2 X-Ref for references to any applications not being converted (i.e., "unavailable"). The conversion logs do not report all such references so it is important to examine the SP2 X-Ref closely. Decide how to handle these references since they may cause compile errors in APPX. If the application will later be converted, change domain references to be defined locally and make note of functions referencing its files for testing later. There may even be references to applications that do not exist in SP2 or are not used anymore; if so, get approval to delete such references. (See item 2.15.)
Item 2.11
There are several issues related to numeric fields and display masks in APPX 3.0.0 which are helpful to know (besides what is in the manual):
- If a mask is not explicitly defined for an item, APPX seems to use an internal display mask of "9-" for a signed numeric field and "9" for an unsigned numeric field (note placeholders are not needed for decimal places). The 'Blank if Zero?' flag determines whether or not a zero is displayed. (Note: It has been requested that APPX change the internal mask to "90-" & "90" respectively.)
- Bug?/Difference: If a signed or unsigned numeric field is negative and there is no sign explicitly defined in the mask if present for the item or in the internal display mask if not, APPX displays question marks whereas SP2 only displays question marks if there is not room for the sign. (Both APPX & SP2 store a sign for an unsigned field. A negative value cannot be entered for an unsigned field but it may be computed via statements.) (Note: It has been requested that APPX print question marks similar to SP2.)
- Bug?/Difference: If a field with decimal places has no mask or if the mask does not have a zero in the units position, APPX does not display a leading zero like SP2 does (for example, APPX prints .00, not 0.00). (See item 2.11.1.)
- Difference: If a leading "-" sign is specified in the mask for an item and the item is not right-justified, APPX displays a leading space for a positive value whereas SP2 does not.
- Bug: When a mask of "90-" is defined for a field with no decimal places and the item is right-justified, APPX does not properly reserve a space for the trailing sign. This causes positive and negative values to not be properly aligned.
Run the APPX Software, Inc. job '!TEST MASKS LIST' or input '!TEST MASKS' in CGL SE to see the behavior of a new APPX version.
The standard conversion utility only generates a numeric mask for exceptional SP2 conditions such as unsigned or zero-filled fields (from SP2 inputs & outputs) and for non-trailing sign, grouping, or currency characters (from SP2 outputs only). The APPX Software, Inc. conversion utility (V05) always generates a mask for output/inquiry processes. If generated, the mask normally contains a zero in the units position, thus avoiding the .00 problem, but there may be other problems. (See items 4.24, 5.12, 9.29, 9.30, 10.15, & 10.19 for more information.) (Also, see item 2.20 for APPX environmental variables affecting handling of mask.)
Item 2.12
Warning: To avoid possible repercussions (such as changing or deleting data accidentally), CANCEL out whenever you encounter something unexpected in APPX and then investigate by calling up the same screen in INQUIRE using the most direct path available or by using FILES EDIT. It is possible that the screen was just improperly displayed the first time (perhaps due to the sequence in which it was accessed) but if you step thru it data will be permanently changed or deleted.
Item 2.13
Note: If strange APPX system errors are suddenly encountered doing everyday tasks not recently changed, suspect corrupted Em's and/or corrupted system variables that can be reset by IPLing. The best course of action is for the system administrator to have everyone else log off the system. He should delete the Em's and Dbg's and then run APPX thru the system menu before allowing any users back on the system. If system menu Em's are being built while users log on, it can cause certain users to get segmentation faults when attempting to run APPX.
Item 2.14
Difference: SP2 uses PF keys while APPX uses OPTION or other named keys (such as END, CANCEL, ADD, DELETE, INQUIRE, CHANGE, HELP, SCAN, SELECT, PREVIOUS ACTIVITY, NEXT RECORD, etc.). The conversion utility converts (PF KEY) references to OPTION and flags most situations that are in doubt. However, there may still be text references to "PF" which are no longer appropriate. The V05 conversion log also flags text references to "PF" (see items 6.4, 8.29, & 9.34; items 9.16, 9.32, & 9.35 will be addressed later). You will usually change PF1 or PF2 to SCAN, PF9 to ADD, PF10 to DELETE, PF11 to INQUIRE, PF12 to CHANGE, PF13 to END, PF16 to END (or possibly to CANCEL), PF17-24 to OPTION 17-24, and PF32 to CANCEL.
Item 2.15
Bug/Note: When using the Toolbox utility Create Executable Modules, remember there can be legitimate reasons for APPX to get a compile error. For example, a subroutine process may have references to labels in other subroutines or in the process invoking the subroutine; such subroutines will not compile independently but will compile at runtime. Also, the function may not be executable in SP2 either; it may be obsolete and/or reference non-existent fields, files, or applications (see items 2.10 & 2.18). If the screen hangs while running this utility, there may be an orphan frame or image in APPX. (See items 1.26 & 1.34).
Item 2.16
Difference (flagged in V05): SP2 allows 79 characters for Default Value and Edit Mask whereas APPX only allows 60 characters. In the case of Edit Mask, this is a critical difference since Edit Mask is used to size the field and must match SP2. If necessary, remove the APPX edit mask by defining the field as ALPHA, not FORMAT, and add commands to edit the field in input processes allowing field entry. For those fields with default values longer than 60 bytes, if it matters, add commands to set these values in any process referencing the field. Beware of commands to restore default values. Warning: The truncation of Edit Mask may not be flagged on conversion logs. (See items 3.2, 4.12, 5.4, & 9.36.)
Item 2.17
Note: Underlining on reports can cause some printers to beat themselves to death (since APPX sends a character, backspace, underscore to do underlining). Laser printers do not have any problem.
Item 2.18
Note: If it is not practical to address some conversion issues in a process that does not compile in SP2, add code to Start of Process in APPX to document this situation and to cancel the job. Use XCopy to copy this code from Start of Process in UTL CS Status function "*CANCEL* OBSOLETE SP2 PROCESS".
Item 2.19
Difference: In SP2, when using a non-unique alternate key to access data, records with duplicate alternate keys are returned in primary key sequence. In APPX, the alternate key must be defined as 'forced' to ensure this behavior. In both SP2 and APPX, if a sort is performed which does not specify the sequence to a unique level, the sequence is unpredictable past the specified level.
Also, note that it is possible for various Wang utilities such as DISPLAY or DL to present data from indexed files in primary key order (due to the Wang DMS file system). On a UNIX machine there is no inherent file access method and programs such as pg present the data as it is stored in the file.
Item 2.20
Note: There is a special FD version of APPX which uses HEX(F) to signify a positive sign (which is the same as SP2). The standard version uses HEX(C). There are several environmental variables that can be set on the command line running APPX 3.0.0 which will modify its behavior, such as the following:
APPX_PRT_SCRIPT=filename APPX_BG_SCRIPT=filename APPX_184_ALIGNMENT=x APPX_200_ALIGNMENT=x APPX_RUN_MEM=nnnnnn (for example, use 256000 to increase memory on PC) APPX_SCRIPT_IN=filename (APPX will use file to generate keystrokes) APPX_SCRIPT_OUT=filename (APPX will record keystrokes in file) APPX_TRAP_RESTRUCT=x (inserts TRAP in action process) APPX_DB_TRAPS=x (enables TRAPs in production) APPX_NET_HASP=1 (needed by APPX for WINDOWS for hasp registration) APPX_184_MASKS=x
Run the APPX Software, Inc. job '!TEST MASKS LIST' or input '!TEST MASKS' in CGL SE to see the results of using a different mask. (See items 2.11 & 8.30.)
Item 2.21
Difference: SP2 allows a GOTO with an undefined label to compile (and only gives an error at runtime if the GOTO is actually executed). APPX gets a compile error if the label does not exist in the same event point or in a called subroutine.
Item 2.22
Note: In APPX 3.0.0, a record in the DOMAIN file in 0AD provides the definition of each field in the Data Dictionary. If the field is actually a domain, the 'Generated?' flag in the first byte is "N"; otherwise, it is "Y". This flag is part of the DOMAIN primary key. Records in the FIELD file in 0AD, on the other hand, provide instances of the definition. For a domain field, there may be several instances. Although the two files, DOMAIN and FIELD, have many fields in common, some of these fields (such as Storage Mask) are now obsolete in the FIELD file. APPX updates the BITMAP, ELEMENT, FILE, and INITIAL files when the Data Dictionary is processed. At runtime the ELEMENT file is used to provide the field definition.
Item 2.23
Note: Before running the conversion utility, it would be wise to process the SP2 Data Dictionary for all the conversion applications (as well as any reference applications) and correct any errors in SP2 first. Otherwise, the conversion may create invalid data in APPX that is not readily apparent. For instance, the conversion utility does not properly handle a SP2 field which is 'same as' a field which is 'same as' another field. Although this condition causes a SP2 error when processing the Data Dictionary, it does not cause an error at runtime so it is easy to go unnoticed.
Item 2.24
EH?/Difference/Conversion EH?: In the SP2 Data Dictionary, the flag 'Use AM/PM if 12-Hour Time?' can be set for a date/time field to control whether or not AM and PM should be displayed and printed for the field if 12-hour (rather than 24-hour) time is used. There is no such capability in the APPX Data Dictionary. However, the flag 'Discard AM/PM?' can be set for an image item in APPX. APPX should offer this flag at the Data Dictionary level in order to emulate SP2. If so, the conversion utility would need to be changed to properly set this field.
Item 2.25
Note: The Validation Table in the APPX Data Dictionary corresponds to the Look Up Table for an alpha field in the SP2 Data Dictionary. The conversion utility will not create an entry in the APPX validation table for a blank value imbedded among other values in the SP2 look up table but this does not cause a problem. SP2 and APPX behave the same since a flag on the image item controls whether or not a blank value is permitted for the field (the flag 'Blank OK?' in SP2 and the flag 'Required?' in APPX).
Item 2.26
Difference: In the SP2 Data Dictionary, Auto Access Path is specified separately for each field defined as 'Same As' another field but is not specified for the root field of a 'Same As' field. In the APPX Data Dictionary, a DLU is only specified for the domain, not for a field based on the domain.
Item 2.27
Difference: Due to the nature of SP2 and APPX, there are some fundamental differences between the two products which can have repercussions.
SP2 handles higher and lower level window files within a single function. APPX has a separate process for each PCF file and each process has its own store buffer for a file. For example, SP2 can do a STORE at a higher level and a RESTORE at a lower level whereas APPX cannot. (See item 8.35.)
Item 2.28
Conversion EH: Each item in this document labeled as "Action" should be reviewed to see whether the conversion utility can or should be enhanced to either flag the item or to flag the item more precisely.
Item 2.29
Note (FYI): Here are some notes in regard to record hold which apply to the PCF file only. Remember, only 1 record can be held at a time but APPX will restore the hold under certain circumstances. A read without hold on the same file does not lose the hold; a read with hold on the same file does. A read with hold on a different file does not lose the hold (because APPX restores it for the PCF file). A write on the same file loses the hold whereas a write to a different file does not. (See item 8.38.)
Item 2.30
Action (flagged in V05 after 08/27/96): Some SP2 terminology was not flagged on earlier conversion logs (such as "PF" references in field default values or references to "SPEED" or "EXPLAIN" or their variations anywhere). Items that should be checked for such terminology include the following: field default values, menu/input images, */**/ERROR/WARNING/MESSAGE/CANCEL commands, and documentation.
Item 2.31
Note (FYI): According to APPX, predefined field --- STATUS CODE (not in the manual) can be used to obtain text messages for failure conditions on commands. Here is one technique:
OPEN aaa filename SHARE? Y FAIL 2 F SET --- MESSAGE ID = --- STATUS CODE F READ --- MESSAGE HOLD 0 FAIL 0 KEY IS MESSAGE ID
(note: you can safely ignore the 'File Not Found' WARNING here; if in full screen edit, use OPTION 88 to accept the screen anyway.)
FT SET --- TEMP 80 = OPEN aaa/filename FT APPEND --- TEMP 80 1 --- MESSAGE TXT FF SET --- TEMP 80 = your error message F CANCEL --- TEMP 80
The --- MESSAGE TXT field is defined as X(500). However, in some cases, it may not contain much information beyond the obvious.