Converting to BBj from Earlier Versions of BASIS Products

BBxProgression/2 and BBxProgression/3 programs must first be converted to PRO/5 in order to work with BBj. For more information, see Conversion from BBxProgression/2 or BBxProgression/3 to PRO/5.

For an overview of the BBj changes made from earlier versions of BASIS Products, see BBj - Changes to Earlier Version of BASIS Products.


Please review all of the conversion information below and back up your original programs before starting a conversion.

Step 1. Run the _keyword utility. This program is part of the standard utilities (basis/utils/std/).

This step can be run in PRO/5 or BBj, but it must be applied to PRO/5 or BBxPROGRESSION/4 tokenized programs.

Several verbs and system variables are reserved keywords in BBj, making them unavailable for use as variables. The _keyword utility scans selected PROGRESSION/4 or PRO/5 programs and generates a listing of proposed keyword changes. It can also update the programs, altering any keywords that are used as variable names so that they will not generate compilation errors in BBj. The complete list of reserved keywords can be found in the text file basis/utils/std/_keyword.dat.

Please review the output from the _keyword utility carefully. Some of the changes it makes might highlight existing program errors. If it finds that the words LET, THEN, ELSE, or any BBx system variables like DAY or TIM were used as variables, there is a good chance that the original code needs to be reviewed and corrected.

Step 2. Recompile your programs for BBj using the bbjcpl program. BBj can directly execute PROGRESSION/4 or PRO/5 programs, so this step is not strictly necessary, but programs that are recompiled for BBj will load faster than PROGRESSION/4 or PRO/5 programs.


Use the following command to convert PRO/5 programs in /prog/bbx/ to BBj programs in /prog/bbj/, with errors logged to error.log:

    bbjcpl –d/prog/bbj/ /prog/bbx/* -eerror.log

Please review the bbjcpl error log and fix any errors before continuing.

Step 3. While BBj maintains a high level of compatibility with earlier version of BBx, it is not identical to PRO/5. The following list describes the differences that are most likely to affect typical application code.

  1. BBj is capable of loading and running programs tokenized in BBxPROGRESSION/4 or PRO/5, but if a program is saved from BBj (or converted to BBj using bbjcpl), it can no longer be loaded in PRO/5. Note that code that does not use BBj-specific features can always be migrated back to PRO/5 using bbjlst and pro5cpl. This is similar to previous level upgrades, for example, from BBxPROGRESSION/4 to PRO/5

  2. The BBj CPL(), LST(), and PGM() functions work with human-readable source code, not PRO/5 tokens. Any utility programs that use these functions to directly manipulate program tokens will need to be revised or rewritten.

  3. The FID() type of BBj-tokenized program files is $84$. The FID() type of PROGRESSION/4- or PRO/5-tokenized program files continues to be $04$.

  4. Some of the values returned by the INFO() function differ from PRO/5. INFO(0,0) is most likely to affect application code. With PRO/5, this string (which identifies the host operating system) is defined in the compile process, so it is directly under BASIS's control. BBj takes this value from the Java Virtual Machine, and the results can vary from one JVM to another. On Windows platforms, Visual PRO/5 returns a string starting with "WIN" for INFO(0,0) while BBj returns a string starting with "Windows".

  5. In GUI environments, the BBj INFO(6,0) function returns "SWING", while the Visual PRO/5 version returns "WINDOWS". If a GUI is not available, INFO(6,0) returns "".

  6. Because BBj is a client/server product, it is important to consider whether some functions will take place on the client or the server. By default, SCALL() executes on the server. SETOPTS byte 8, bit $08$ can be set to force SCALL() to execute on the client. The difference between how PRO/5 and BBj handles the screen is most obvious when returning from an SCALL. When returning from an SCALL in BBj, it is necessary to use the 'RS' mnemonic.

  7. Minor changes in the DSZ, SYS, and TIM functions may affect your code. Review the documentation notes for these functions, and review your code if necessary.

  8. The amount of memory available to BBj is determined by the JVM, not the START size. The workspace memory is dynamic. The number of pages specified in command-line –m option or in the START verb are ignored. One effect of this is that BBj will never generate an !ERROR=31. Out of memory conditions in BBj are signaled with !ERROR=33, which indicates that all the memory allocated to the JVM has been used.

  9. BBj cannot lock the system clipboard, so the CLIPLOCK Verb is a no op. See Clipboard Verbs and Functions for more information.

  10. BBj does not support the CISAM file type.

  11. The BBj template driver reports an integer overflow on any attempt to assign an out-of-range value to a signed integer field (template type I). For example, given the following line of code, PROGRESSION/4 or PRO/5 prints -1, but BBj generates !ERROR=41:
    0100 DIM X$:"I:I(1)"; LET X.I=255; PRINT X.I

  12. By default, BBj templates do not allow duplicate field names:
    !ERROR=17 (Duplicate field name: I)
    0100 DIM X$:"I:I(1),I:I(1)"
    This can be overridden using SETOPTS byte 8 bit $04$.

  13. In startup scripts and SCALL() functions, change pro5 and vpro5 to bbj, pro5cpl to bbjcpl, and pro5lst to bbjlst. In most cases, it is enough to just change the program name, since most of the option flags are unchanged.

  14. The BBj SETTIME verb always generates an !ERROR=18.

  15. In BBj, the first RESOPEN() function call returns a handle value of 1. In Visual PRO/5, the first RESOPEN() function call returns a handle value of 0.

  16. In PRO/5, when performing a SQL SELECT operation from a single table using the internal SQL engine, the SQLTMPL() template is coincidentally the same as the file template as defined in the data dictionary. In BBj, there is not necessarily any correlation between the SQLTMPL() template for any SQL SELECT and the actual file template in the data dictionary. See SQL Select Modifications for more information.

  17. BBj does not support plotter (alias D*) devices.

  18. See Function and Edit Keys for BBj Character Devices for changes that affect the 'FL' and 'EL' mnemonics.

  19. In PRO/5, READRECORD (0,SIZ=1)KEY$ returns $0D$ for carriage return (ENTER) and $0A$ for line feed (Ctrl-J). Because Java does not distinguish between carriage return ($0D$) and line feed ($0A$), BBj returns $0D$ for both keys.

  20. In BBj, the SQL engine performs more extensive verification than PRO/5 and Visual PRO/5 during the prepare phase. In some cases, this can result in errors being reported on the SQLPREP() instead of the SQLEXEC(). For example, attempting to prepare a DROP TABLE statement specifying a table name that does not exist will report an error on the call to SQLPREP().

  21. Several enhancements have been made to the grid control in order to improve usability. These changes may cause some problems with Visual PRO/5 programs that use grids. To cause grid controls to work the same way in BBj as they do in Visual PRO/5, use SETOPTS byte 8, bit $10$. For more information, see General Grid Enhancement Information.

  22. In BBj, the MINICON mnemonic does not support the .exe, .dll and .icl file types.

  23. See the SETTERM documentation for an example of how to use this verb for applications that rely on the FID(0) and will be run in a Web browser.

  24. BBj uses ASCII resource files (.arc) instead of binary resource files (.brc). See Converting Resource File Formats for instructions on how to automatically convert binary resource files into ASCII resource files using ResBuilder's command line parameters.

  25. BBj uses a third-party library to access the serial ports. This library is currently only shipped with the Windows and Linux BBj ports.

  26. In BBj, new character windows created with the WINDOW mnemonic do not automatically inherit the contents of windows directly beneath them. See WINDOW Mnemonic - Create a Window (Terminal Device).

  27. In order to see the error message, UI ack-back has to be enabled. Like all CUI/GUI component errors, if you run BBj in a production environment all such error messages are suppressed for the sake of speed and efficiency. A change to development mode settings will re-enable UI ack-back and show the error messages.

  28. BBj type-checks several MODE options to help detect possible errors. The following modes must be set to a numeric value: ASPECT, KEYWAIT, LMARGIN, TMARGIN, RMARGIN, BMARGIN, HEIGHT, WIDTH. The following modes must be set to an integer value: COLS, COPIES, CPCOLS, CPLINES, EPCOLS, EPLINES, FONTSIZE, FORM, LOCAL, REFDELAY, ROWS, LINES, SPCOLS, SPLINES, TABS, WAIT, XPOS, YPOS, BAUD, DPI, FOCUSDELAY.

  29. In programs using a hybrid data access approach where the VPRO/5 program opens an ODBC connection to a BBj server using the BBj ODBC Driver, change any SQLOPEN calls to specify the name of the database in BBj instead of the ODBC DSN.

  30. BBj does not automatically LOCK files opened with ISZ=. If the file needs to be LOCKed then the LOCK verb should be used on the open file.

  31. In Visual PRO/5 and PRO/5, programs may have taken advantage of undocumented behavior of the filesystem to perform an EXTRACT on a channel while having the same file opened on a second channel without throwing an !ERROR=0. Most often the EXTRACT was employed to avoid moving the record pointer with a READ. Naturally this coding practice is illogical and will fail with an !ERROR=0 in BBj’s more robust filesystem implementation. The code fix is to replace the EXTRACT with a READ containing a "DIR=0" to prevent the file pointer from changing.

  32. In BBj 17.0 and higher, BBj SysConsole and TermConsole both ignore the 'UC' mnemonic with translated function and edit keys. PRO/5 would capitalize text that might have been loaded into function and edit keys when the 'UC' mnemonic was active, where BBj now does not.

  33. Although the ADDR and DROP verbs are functional in BBj, their use is discouraged. The BBj program cache automatically adds and drops programs as needed; explicitly adding and dropping programs is no longer necessary, and can interfere with BBj's automatic caching. In BBj 20.0 and higher, setting the IGNORE_ADDR_DROP STBL("!COMPAT") option to TRUE will cause BBj to ignore the ADDR and DROP verbs. After setting this option to TRUE, legacy applications should be carefully tested to ensure that they don't include assumptions about the values returned by the PUB() function.

For more information, refer to BBj Specific Documentation > Language Changes in the online Table of Contents.