Section 8: Commands
Commands
Use APPX ILF X-Ref (reliable) and APPX PDF X-Ref (not so reliable) from item 2.9. Check for APPX Inquiry Process too!
Item 8.1
Bug (fixed in APPX 3.0): APPX is only checking the first 22 characters of name on the COPY command. This can cause a duplicate label error at compile time. This can be avoided by using GOSUB instead (now that you can GOSUB to another application).
Item 8.2
Bug (FYI): When editing rules in Application Design, APPX may not properly handle the options to Move or Copy commands! The screen may not redisplay properly and it is wise to exit and reenter the event point before doing any further editing. Upon reentering you should confirm that the commands were moved or copied properly since some commands can be deposited in the wrong place.
Item 8.3
Bug (flagged in V05): APPX 1.8.4 can erroneously return a FALSE condition following an IF EXIST on a shared file if the current database does not own the shared file. One work-around is to create the file within the current database before specifying the Use Database. However, this work-around has a drawback since a related bug (described in item 4.3) means that any restructures must be performed on both files. Check files used in IF EXIST commands to see if they are shared and then decide how to address. (See items 2.8 & 4.3.)
Item 8.4
Bug (fixed in APPX 3.0.0): APPX does not always process a CALC command correctly. The problem seems to occur when there are too many significant digits. Consider the following example: CALC X = 47*(21+(7/12)) where the correct answer is 1014.41666666667. APPX 2.3 gets a numeric overflow error (whereas APPX 1.8.4 and APPX 2.1 both get the wrong answer of 14.41666666667). To avoid problems, rewrite code to use COMPUTE commands, not CALC. Run APPX Software, Inc. UTL CS utility "Check APPX CALC Statement" to check a new version of APPX. (See item 8.32.)
Item 8.5
Conversion Bug (fixed in V05): The V04 conversion can generate references to SUBMIT CLASS which is not a valid PDF in APPX. Run a X-Ref in APPX and delete all such references. The V05 conversion changed SUBMIT CLASS to SUBMIT PRIORITY. (Note: These may been deleted already by item 7.10.)
Item 8.6
Conversion Bug (fixed in V05): The V04 conversion can generate references to DISPOSITION OPTIONS. Although this is a valid PDF, it is not documented and it behaves peculiarly. It does not appear to be needed so the best approach is to delete all such references. The V05 conversion does not generate such references. (Note: These may been deleted already by item 7.10.)
Item 8.7
Difference (flagged in V05): APPX differs from SP2 in the behavior of CNV BIN; SP2 truncates a decimal number to an integer whereas APPX rounds. This means that the SP2 technique to use CNV BIN to truncate will not work in APPX. The converted code will typically look like this:
CNV BIN aaa WORK alpha field = aaa number field CNV BIN aaa number field = aaa WORK alpha field
Rewrite code to use CALC commands as follows (provided X is not being used):
SET --- X = aaa number field
IF --- X GE
T CALC X = @FLOOR(X)
F CALC X = @CEIL(X)
SET aaa number field = --- X
Item 8.8
Difference (flagged in V05): APPX differs from SP2 in maintaining a hold on a record when changing its primary key. In SP2, you can read a record with hold, (optionally store it), change the primary key, write it, (optionally restore it), and delete it in that order. In APPX 1.8.4, you must DELETE the record before the WRITE with the new key to avoid getting a "record not held" error at runtime. The conversion log flags all uses of DELETE for inspection. In addition, the APPX Software, Inc. UTL CS utility "APPX STMT I/O List" can be used to review these commands.
Item 8.9
Difference (flagged in V05): APPX differs from SP2 in that APPX considers each BEG READ or READNEXT command to be a separate thread with its own pointer. This means that if a BEG AT or END AT command is applicable, each BEG READ or READNEXT command must have its own.
For example, the conversion message "Inspect READNEXT within BEG READ loop" should be researched to determine if both read's affect the same file. If so, a BEG AT should be inserted before the READNEXT to position the pointer. In another example, there may be a single BEG AT serving two alternating READNEXT commands in SP2. This would not work in APPX (one READNEXT would start at the beginning of the file). A solution would be to put the READNEXT in a subroutine at the end of the event point and replace the READNEXT's with GOSUB's.
Note that SP2 and APPX behave the same where there is an initial BEG AT/END AT for a READNEXT and then a single BEG AT or END AT affecting the same READNEXT statement. The BEG AT with no END AT will establish a new beginning pointer and effectively set the END AT pointer to end of file. The END AT with no BEG AT does not change the current pointer (it continues reading from wherever it was) but it does establish a new ending pointer.
Likewise, SP2 and APPX behave the same where there is a READ followed by a READNEXT with no BEG AT. The READ will establish the pointer for the READNEXT (assuming the same key path is used).
Also, note that SP2 and APPX behave the same in regard to appending HEX(00)'s or HEX(FF)'s where the field specified in the BEG AT or END AT is shorter than the key used to read the file.
The APPX Software, Inc. UTL CS utility "APPX STMT I/O List" can be used to review all BEG AT/END AT/BEG READ/END READ/READNEXT commands in the application.
Item 8.10
Difference (fixed in 3.0): In earlier releases of APPX, the BEG AT and END AT commands must be in the same event point as the associated BEG READ or READNEXT in order to be effective. In SP2 they could be in different command series. The APPX Software, Inc. UTL CS utility "APPX STMT I/O List" can be used to review these commands. Warning: This does not cause a compile error in unfixed releases of APPX; the program just does not run properly!
Item 8.11
Action/Difference (compile error): The END LOOP and END READ commands must have matching BEG LOOP and BEG READ commands or it causes a compile error in APPX whereas SP2 allowed this. Both SP2 and APPX allow BEG LOOP and BEG READ commands without a matching END LOOP and END READ. To find BEG LOOP/END LOOP commands, run the APPX Software, Inc. UTL CS utility "APPX STMT 'BEG LOOP/END LOOP' List". To find BEG READ/END READ commands, run the APPX Software, Inc. UTL CS utility "APPX STMT I/O List". If there are any mismatches, you must rewrite the code in APPX to eliminate these.
Item 8.12
Difference (flagged): The conversion log flags the use of MODE since many (if not most) commands that reference MODE should be modified to reference INTERACTIVE PHASE instead. Remember that it is possible to be in ADD mode at the same time interactive phase is DATA MODIFICATION (for instance, when returning to a higher level via PF4 PREVIOUS ACTIVITY or when editing a scrolling record.) However, beware of complicating factors. For instance, do not change the use of MODE in a footer window (since INTERACTIVE PHASE will never be DATA ADDITION). Also, reconsider if testing NE condition or if testing to switch modes. Note that a scrolling frame executes After PCF-Read twice in the DATA SCROLL INTERACTIVE PHASE; this may have repercussions if mode was being used to set a flag which is then tested independently. (See item 9.12.)
MODE: ADD INTERACTIVE PHASE: DATA ADDITION
DELETE DATA DELETION
INQUIRE DATA INQUIRE
CHANGE DATA MODIFICATION
Item 8.13
Action/Difference (partially flagged in V05): Fields can be defined as TOTAL fields in SP2 whereas there is no such field type in APPX. Instead, APPX associates two areas with a NUMERIC field, the current area and the total area.
The TOTAL command (as well as automatic totaling) affect the total area while other commands such as SET, COMPUTE, and RESTORE affect the current area. The SET TOT command is used to move the total area into the current area.
In order to emulate SP2, the conversion utility inserts a SET TOT command in front of any command using a SP2 total-type field in non-detail windows. Although the first SET TOT is necessary for a given field, needless repetitions only serve to obscure the code and can actually cause a bug at runtime if the SP2 total-type field has been modified by SET/COMPUTE/RESTORE commands.
The best approach to emulate SP2 is to have a single SET TOT (to itself) for each SP2 total-type field (watch out for use in loops!) at the beginning of the event point and delete all the other SET TOT'S. In addition, if the SP2 total-type field is modified by SET/COMPUTE/RESTORE commands and if it is defined on the image, add a DISPLAY command following the SET/COMPUTE/RESTORE commands and change the Auto-Display type on the image from '4'=Auto-Total Value to '0'=None. Also, if there is a TOTAL command on a SP2 total-type field in a non-detail window, add a SET TOT following the TOTAL command and if the field is defined on the image, change the Auto-Display type on the image from '4' to '0' and check for a DISPLAY command. (The conversion utility generates a DISPLAY command following a TOTAL command in a subtotal window but it may drop the 22nd character of the field name.) Note that if a SET TOT is generated for a SP2 command library which is copied only into detail windows, the SET TOT should be deleted.
The conversion log currently warns to inspect SET TOT commands and to inspect SET/COMPUTE/RESTORE commands on total-type fields. However, it does not yet warn if a TOTAL command is used in a non-detail window. Use the APPX Software, Inc. UTL CS utility "APPX STMT 'TOTAL/SET TOT' List" to find these by blanking the opcode for SET TOT and selecting Frame Class NE RECORD in the sort. (See items 1.66, 8.27, 10.23, & 11.4.)
Item 8.14
Difference (flagged in V05): NEXT DATABASE is cleared in APPX by OPEN, CREATE, and SCRATCH commands. Any use of NEXT DATABASE should be carefully reviewed to see if this causes a problem. (See item 10.25.)
Item 8.15
Action/Bug?/Difference (DATE ADD flagged in V05 + compile errors): SP2 can handle some uses of DATE ADD which cause a 'date invalid' error at runtime in APPX 3.0.0. For example, when subtracting one month from a 'month only' date field with month 01, SP2 got month 12 whereas APPX got an error (APPX handled adding months OK - it got month 02 when adding 13 months). Also, when subtracting one year from a 'year only' date field with year 00, SP2 got year 99 whereas APPX got an error. Errors appear at risk when subtracting from a date field without a higher component than the unit. One work-around is to perform the DATE ADD using a work field with the next higher component defined. The conversion log flags all DATE ADD commands. Unit values are defined as: 8=CC, 7=YY, 6=MM, 5=DD, 4=hh, 3=mm, 2=ss, 1=th.
SP2 also allows some uses of DATE BTW commands that will cause a compile error in APPX. For instance, SP2 allows days (unit 5) on a DATE BTW command for a month/day date field whereas APPX does not (although DATE ADD compiles OK).
Use the APPX Software, Inc. UTL CS utility "APPX STMT 'DATE ADD/DATE BTW' List" to review all DATE ADD/DATE BTW commands in the application.
Item 8.16
Difference (flagged in V05): In SP2 the short version of SET MNTH (type S) returns the three-character month in upper case; APPX returns it in upper/lower case (just the first letter is capitalized). Check usage to see if this matters.
Item 8.17
Difference (compile error): SP2 and APPX differ in regard to commands allowed on WORKING-STORAGE files (pseudo-files). In SP2, IF EXIST/SCRATCH/CREATE commands can be executed and READ/WRITE/REWRITE/BEG READ/READNEXT commands can be compiled but cause a fatal error if executed at runtime. All such commands cause a compile error in APPX and should be deleted. Use the APPX Software, Inc. UTL CS utility "APPX STMT I/O List" for the WORKING-STORAGE file to find these commands. (See item 1.74.)
Item 8.18
Difference (flagged in V05): APPX handles the cursor option of the POSITION command differently than SP2. For example, the placement of the cursor will be one position to the left on the screen in SP2 than it will be in APPX for the same CURSOR COLUMN. Check usage to see if this difference matters. (See item 9.15.)
Item 8.19
Difference (flagged in V05): SP2 uses the RUN command to invoke execution of a menu, job, or function. The conversion utility converts this to be INPUT, INQUIRY, JOB, MENU, OUTPUT, QUERY, STATUS, SUBR, UPDATE, etc. (SP2 RUN commands invoking external functions are converted to COPY) and Version 05 sets invocation type to RELATED. If memory files or such do not need to be shared, invocation type can be set to DETACHED. The conversion log flags all uses of the SP2 RUN command.
Item 8.20
Difference (flagged in V05): ENTRY LEVEL in APPX pertains only to DATA ADDITION and is undefined and hence unreliable in DATA MODIFICATION, unlike SP2 where (ENTRY) was always 2 in CHANGE mode. To check for the equivalent of SP2 secondary entry, code as follows in APPX: (see item 9.10)
IF --- ENTRY LEVEL GE 2 AND --- INTERACTIVE PHASE EQ DATA ADDITION OR --- INTERACTIVE PHASE EQ DATA MODIFICATION OR --- INTERACTIVE PHASE EQ DATA INQUIRE
Item 8.21
Note (FYI): The AT FIELD command only works in the Option Intercept event point (it always returns a False condition in other event points). This is not a difference since the AT FIELD command is only valid in PF Intercept in SP2.
Item 8.22
Note (FYI): You can use Option 88 to bypass a bogus ERROR message when editing commands. ERROR messages can be caused by the following conditions:
- APPX 2.x bug is only checking the first 22 characters of name on COPY command (fixed in 3.0.0).
- A field defined as >= 0 is being set to or multiplied by negative value (it is OK to multiply by -1 in order to force a positive value but any other use should probably be investigated).
- A validation table exists for a field and the field is being set to a value not in the table (this condition should be corrected if possible - you can use the APPX Software, Inc. UTL CS utility "APPX STMT 'Format 5' List" to list commands where that field is being set or tested.)
Item 8.23
Bug/Difference (flagged in V05): APPX 2.3 (thru 3.0.0) differs from SP2 in its handling of ALTERNATE IMAGE NUMBER as discussed below (see items 1.42, 1.43, 9.26 & 10.11). If (ALTERNATE NUMBER) is not being explicitly set in SP2 wherever it is used, add code in APPX to do so. The Input/Output conversion logs flag all Set Alternate No. command series which have commands. In addition, the Commands conversion log flags all commands setting (ALTERNATE NUMBER) which are not in a Set Alternate No. command series. (The APPX Software, Inc. UTL CS utility "APPX STMT 'Format 5' List" can be used to review code by entering --- ALTERNATE IMAGE NUMBER as app/field 1 in job specs.)
SP2 sets (ALTERNATE NUMBER) to 1 before the first execution of a standard window each time thru and sets (ALTERNATE NUMBER) to 0 before the first execution of a repeating window each time thru.
APPX initializes ALTERNATE IMAGE NUMBER at 0 at start of process and never changes it (except in INQUIRY processes by selection of a key-entry frame); otherwise, it remains as last set by commands.
Also, note the following HELP text for Frame Type in APPX 3.0.0:
"Frame Type governs the execution of an image (or images) for the frame. The Frame Type options are:
> NORMAL executes the first (lowest numbered) alternate image unless another image is explicitly selected with statements and the predefined field ALTERNATE IMAGE NUMBER. (See bug in item 1.42.)
> OPTIONAL executes the image that is identified by the Normal Frame Type above, with the following exception: If the value in the predefined field ALTERNATE IMAGE NUMBER is 0, do not execute an image.
> REPEATING executes the image repeatedly until the value in the ALTERNATE IMAGE NUMBER is set to 0 by statements."
Note that OPTIONAL frames are converted from SP2 windows with code in Set Alternate No. or with 'Alternate Window No.'<>"1". REPEATING frames are converted from SP2 windows with 'Repeat?'="Y". If there are no commands to set ALTERNATE IMAGE NUMBER, REPEATING frames execute only if the current value is non-zero.
Item 8.24
Difference (flagged in V05): (RECORD NUMBER) can be used in SP2 to provide a record count whereas RECORD NUMBER has not yet been implemented in APPX and always returns zero. This is flagged on the conversion log.
Item 8.25
Bug (fixed in APPX 3.0 Beta): In APPX 1.8.4, commands referencing screen items with appearance numbers do not always work properly. For instance, OK INPUT and NO INPUT do not work right. For some operations the problem is caused by APPX always using appearance #1. Sometimes the use of a constant other than 1 as appearance number causes a compile error (for example, DISPLAY on appearance #2). (See items 9.3 and 10.3.)
Item 8.26
Difference (flagged in V05): SP2 could successfully use END FN in a sort (for example, to quit sorting after processing a certain number of records). This is converted to EXIT in APPX which causes a system error at runtime when used in a query (see item 1.12). Modify code to set INCLUDE RECORD to "0" or "N" instead.
Item 8.27
Action/Difference (partially flagged in V05): When SP2 executes a TOTAL command, it rounds the source value before accumulating; APPX does not. In certain instances, this can result in printing reports where detail values do not sum to total values. One way to overcome this is to set the TOTAL field to the source field and TOTAL the TOTAL field as follows (see item 8.13 for how TOTAL works in APPX):
SET CIC WORK TOTAL COST 9 2 = CIC WORK DETAIL COST 6 3 TOTAL CIC WORK TOTAL COST 9 2 + CIC WORK TOTAL COST 9 2
The conversion log flags any TOTAL commands where rounding is a problem with a message to revise rounding. However, prior to 07/12/96, it was not flagging TOTAL commands adding the variable (D). These can be found by using the APPX Software, Inc. UTL CS utility "APPX STMT 'Format 5' List" to search TOTAL commands (opcode 78) for "--- D" in the 2nd application ID/field name.
Item 8.28
Difference (flagged in V05): APPX differs from SP2 in some respects in its treatment of the SET command when used to set alpha field = number field. The problem occurs if SP2 is testing for a specific result since APPX may format the result differently. The only known difference is when the number is an indexvariable with value zero (SP2 gets 0 whereas APPX gets 0.000000000000000 unless setting a format field with right alignment and 0-pad in which case there is no difference). This can be overcome by using a numeric work field, rather than the indexed variable, to set the alpha field. Non-zero values appear to convert the same. If other situations causing differences are discovered, it may be possible to use the CNV TEXT command instead. The conversion log flags this condition but it may not be worthwhile to investigate since differences are rare. The APPX Software, Inc. UTL CS utility "APPX STMT 'Format 5' List" can be used to list the actual commands by entering "ALPHA" as basic field type 1 and "NUMERIC" as basic field type 2. To see only commands using indexed variables, also enter "---" as app ID 2.
Item 8.29
Difference (flagged in V05): Since "PF" terminology is not applicable in APPX, modify "PF" text in ERROR, WARNING, and MESSAGE commands as appropriate. (See item 2.14.)
Item 8.30
Difference (all BEG AT's flagged in V05): Whereas both SP2 and APPX use 'D" to signify a negative sign in a packed decimal field, SP2 uses 'F' to signify a positive sign and APPX uses 'C' (unless the special FD version of APPX is used). Also, in both SP2 and APPX, a date field is stored as packed decimal and a blank date is stored as -1. For instance, a blank month-only date field would be stored as HEX(001D) in both systems. However, month '01' is stored as HEX(001F) in SP2 and as HEX(001C) in APPX. This means if a blank month-only date field is used in a BEG AT command, month 01 will be skipped in APPX. Conversely, if month 01 is used, APPX will include blank months.
Although a single component date field is the likeliest scenario to cause a problem, using other date fields with BEG AT may also be at risk. Fortunately, the most common types of date fields such as ymd, cymd, or md are OK but beware ym. The APPX Software, Inc. UTL CS utility "APPX STMT I/O List" can be used to review BEG AT commands. Also, the "APPX FILE File List" will list files with dates in key fields by entering "Y" to 'Only Files w/Date in Key?'. (See item 1.22.)
Item 8.31
Difference/Conversion EH? (FYI): SP2 and APPX can behave differently when setting partial components of a date field. For example, when setting a ym date field from a non-blank year-only date field, SP2 sets the month component to the current month whereas APPX sets it to month '01'. (See item 8.36.)
Item 8.32
Bug (fixed in later engines): APPX 3.0.0 Optimized may not divide properly. For example, in the divide test 14782712.00 / 197064.93 = 75.01 (rounded to 2 decimal places), the CALC command (as well as COMPUTE commands using work fields, not variables) may get the wrong answer of 29.34. Run APPX Software, Inc. UTL CS "Check APPX CALC Statement" to check a new version of APPX. (See item 8.4.)
Item 8.33
Difference (all WRITE commands flagged in V05): Due to the increased speed in performance of computers running APPX, WRITE commands for files with a date/time stamp in the key may fail since the key may no longer be unique. If the date/time stamp is being used to make the key unique, code must be present to loop back to reset the date/time stamp and retry the WRITE on a FALSE condition. The conversion log flags all WRITE commands for inspection but it only matters on those files with a date/time stamp in the primary key or in any alternate/unique keys.
The APPX Software, Inc. UTL CS utility "APPX FILE File List" will list files with dates in key fields by entering "Y" to 'Only Files w/Date in Key?'. The APPX Software, Inc. UTL CS utility "APPX FIELD File List" will list all date fields by entering "DATE" as 'Basic Field Type'. The date field list is more useful for this purpose if you change the sort order to be file name 1st and field name 2nd (you might want to specify subheading to be NO on file name to conserve paper since the file name is given on each detail line). If desired, the APPX Software, Inc. UTL CS utility "APPX STMT I/O List" can be used to review all WRITE commands. (See item 8.36 too.)
Item 8.34
Difference (fixed/flagged): SP2 allows BL, NB, and BW as the relation on IF/AND/OR commands whereas APPX does not. The conversion utility converts BL to EQ and NB to NE. It flags the use of BW with the message "Revise Relation".
Item 8.35
Action/Difference/Conversion EH: 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. As a result, SP2 can do a STORE at a higher level and a RESTORE at a lower level whereas APPX cannot. The conversion utility does not flag this condition. Run the APPX Software, Inc. UTL CS utility "APPX STMT 'STORE/RESTORE' List" to review these commands.
Item 8.36
Action/Difference/Conversion EH (all WRITE commands flagged in V05 but more action needed): When setting or comparing a date field to a non-date field or a non-date field to a date field, SP2 and APPX may get different results. This is because APPX forces date components to have valid values. For instance, APPX forces month value 00 to 01 and month values 13-99 to 12; day value 00 to 01 and day values 29-99 to 28-31 (depending upon the month); hour values 24-99 to 23; minute values 60-99 to 59; and second values 60-99 to 59. If the date/time field is being used to make a key to a file unique, this can result in records not being written in APPX.
For example, Citrus World sets an hh-ss date key field from a 6 digit number field being incremented by 1. This works in SP2 since SP2 allows the time to be set from 00:00:00 thru 99:99:99 but in APPX this produces duplicate keys due to capping hours, minutes, and seconds. In another example, if an alpha field is set from a hh-mm date field, SP2 gets "00000000hhmm0000" whereas APPX gets "00000101hhmm0000".
Since the conversion program only flags one potential trouble spot and does not flag this problem directly, further investigation is required. To list all date to non-date commands, run the APPX Software, Inc. UTL CS utility "APPX STMT 'Format 5' List" and enter DATE for basic field type 1 and NONDATE for basic field type 2. To list all non-date to date commands, enter NONDATE for basic field type 1 and DATE for basic field type 2. The APPX Software, Inc. UTL CS utility "APPX FIELD File List" will list all date fields by entering "DATE" as 'Basic Field Type'. To see selected fields, just enter the field names as record selections in the sort. (See item 8.33 too.)
Item 8.37
Difference (flagged): The conversion utility flags use of the CNV ZONE command in SP2 since there is no counterpart in APPX. However, the equivalent functionality can be programmed. See the subroutine processes "*EX* CNV ZONE ALPHA TO NUMERIC" and "*EX* CNV ZONE NUMERIC TO ALPHA" in application UTL CS for examples of the necessary code.
Item 8.38
Action/Difference: When a record has been read with hold, SP2 preserves the hold after a WRITE to the same file has returned a False condition whereas APPX loses the hold. This means the following code works in SP2 but does not in APPX (regardless of whether the file is the PCF file or not):
READ aaa file1 HOLD 1 FAIL 0 KEY IS file1 key
... various commands without T/F flags ...
WRITE aaa file1 FAIL 0
F REWRITE aaa file1 FAIL 0
One solution would be to modify the code following the WRITE as follows:
F STORE aaa file1 RECORD F READ aaa file1 HOLD 1 FAIL 0 KEY IS file1 key FT RESTORE aaa file1 RECORD FT REWRITE aaa file1 FAIL 0
Since the conversion log does not flag this condition, run the APPX Software, Inc. UTL CS utility "APPX STMT I/O List" and investigate any code where the same file has both WRITE and REWRITE commands in the same event point. (See item 2.29.)