ProvideX. Conversion Handbook

Transcription

1 ProvideX Conversion Handbook Introduction 3 BBx Conversion 4 Open BASIC Conversion 18 Thoroughbred Conversion 20 MicroShare Conversion 22 Syntax Unique to ProvideX 24

2 ProvideX is a trademark of Sage Software Canada Ltd. All other products referred to in this document are trademarks or registered trademarks of their respective trademark holders Sage Software Canada Ltd. Printed in Canada 8920 Woodbine Ave. Suite 400, Markham, Ontario, Canada L3R 9W9 All rights reserved. Reproduction in whole or in part without permission is prohibited. The capabilities, system requirements and/or compatibility with third-party products described herein are subject to change without notice. Refer to the Sage ProvideX website for current information. Monday, May 25, 2009

3 Conversion Handbook This document discusses the tools and some of the issues to consider when converting applications to ProvideX from other Business Basic languages. It also provides some information on their differences, and lists the functionality that is native to ProvideX. Int roduction Topics BBx Conversion, p.4 Open BASIC Conversion, p.18 Thoroughbred Conversion, p.20 MicroShare Conversion, p.22 Syntax Unique to ProvideX, p.24 Before You Start While ProvideX offers general compatiblity with these other Business Basic languages, it is recommended that you consult with a ProvideX Sales or Support representative to determine exactly which options may be required before you proceed with any conversion. We also suggest that you review the ProvideX Language Reference and the ProvideX User s Guide for complete details on ProvideX syntax and functionality. Converting to ProvideX offers a reliable, cost-effective solution for migrating valuable legacy code to newer, more advanced, technologies. ProvideX Basic supports most of the syntax and functionality of other Business Basics, but the language also has some unique properties. For this reason, this document also includes a section on Syntax Unique to ProvideX, p.24. ProvideX is especially suited for leveraging your existing applications and data. Most character-based applications would present the least complicated conversion, and with minimal code changes. On the other hand, some GUI-based front-ends may require a more complex set of routines. Remember that the programs described in this document serve only as a starting point for your conversion process and may require further modifications. Copyright 2009 Sage Software Canada Back 3

4 BBx Conversion BBx Conversion BBx Conversion BMK Topics This section discusses conversion to the ProvideX language from BBx. BBx Conversion, GUI-Based Standalone, p.4 BBx Conversion, Character-Based, p.10 How to Start the New Application, p.14 BBx Emulation, p.14 Direct Translation from BBx, p.16 BBx Conversion, GUI-Based Standalone The GUI-based utility is designed to convert BBx programs and files to ProvideX without the need for a BBx executable on the computer that will be performing the conversion. *conv.bbx/gui_cv converts BBx data files available in BBx/4 (Direct, Sort, MKeyed, Indexed and String). Data files added to later BASIS products cannot be converted to ProvideX using this program. XKeyed files and +2GB files should be converted using the character-based program (which does require a copy of the BASIS executable). To start the conversion, run ProvideX, then type the following at the command line: cwdir "/pvx/lib/_conv.bbx" run "gui_cv" The first screen of the conversion routine appears similar to the following: Copyright 2009 Sage Software Canada Back 4

5 BBx Conversion The options available on the primary Conversion Setup panel are outlined below: Test for errors without converting Input programs / files Convert Programs Convert Files Checkbox indicating to step through the conversion process without actually converting any of the programs or files. This produces an exception report (log file) in advance without actually converting any of the programs or files. The exception report can then be analysed to determine if there will be any compatibility issues. Indicates the current directory for the BBx programs & data files. To change to a new directory, click the button, then click. When the correct directory is selected, click the button to force GUI_CV to scan for all files (including all subdirectories). Individual files can be removed from the list of programs/files to convert by clicking the button. Checkbox enabled by default. When de-selected, the conversion program will not convert any programs. Checkbox enabled by default. When de-selected, the conversion program will not convert any files. Output Directory Indicates the (ProvideX) output directory. Click to locate the directory. You must select a directory different from the input directory (the conversion will not allow the input and output directories to be the same). GUI_CV will re-create the entire tree structure like it exists in the input directory. Path & name of log file Indicates the log file for determining the overall status of the conversion. Click to locate the file. This is a flat ASCII file that can be accessed with any text editor or word processor. The log will contain any error or warning messages generated by the conversion. It can also provide a complete list of all files & programs converted. If you don't want the converter to write a log file, you must leave this field empty. The Conversion Setup panel is divided into the following sub-folders: Logfile Options, p.6 File Options, p.7 Program Options, p.8 Copyright 2009 Sage Software Canada Back 5

6 BBx Conversion Logfile Options The options available in this sub-folder are outlined below: Log name of converted file Log pgm lines that contain $0A$ Log files with non-ascii characters Log records with non-ascii characters Append to log file Log item(s) Checkbox indicating that all names of the converted programs/files will be stored in the log file. Checkbox indicating that each and every program line that contains $0A$ will be listed in the log file. Checkbox indicating that the name of the data file will be written into the log file when a non-ascii character was found in any of the records of that file. Non-ascii in this context are all characters that are smaller than a space or larger than a tilde in the ASCII table (all characters below 0x20 and above 0x7E). Checkbox indicating that each and every record that contains non-ascii data will be written to the log file. Checkbox indicating that errors and warning messages will be appended to the end of the log file. Not selecting this setting will cause an existing log file to be overwritten. List of checkboxes that allows you to select which items may be written into the log file if the converter encounters them. Copyright 2009 Sage Software Canada Back 6

7 BBx Conversion File Options The options available in this sub-folder are outlined below: VARIABLE length record files No maximum record count Don't convert STRING files Create files with $0A$ separator Add indices after conversion Checkbox indicating that ProvideX will create all of the Keyed files using variable length records that will reduce disk space requirements and increase file performance. Checkbox indicating that Keyed files will be created with no preset limit to the number of records in a file. Checkbox indicating that all String (non-bbx files) will be skipped during conversion. Checkbox indicating that all Keyed files will be created with a $0A$ field separator instead if the standard $8A$ separator. GUI_CV will no longer replace $0A$ in data records by $8A$ (the data records will remain unchanged). Also select the Use $0A$ in Direct/Mkeyed/Indexed setting under the Program Options tab in order to change the BBx file creation verbs to create files with a $0A$ field separator. Checkbox indicating that all multi-keyed files will be created with the primary key only. Only after converting all data will GUI_CV add the secondary keys to the file. This result in a huge performance gain when converting larger files or files with a large number of secondary keys.. Copyright 2009 Sage Software Canada Back 7

8 Use direct BBx file access if available Convert SORT files to KEYED files Oem to Ansi conversion in data files BBx Conversion Checkbox indicating that the use of use ProvideX add-on package (BBx Keyed File Read). GUI_CV will access BBx data through this interface (if activated) and no longer analyse the binary contents of the BBx data. This may result in a performance gain during conversion. Converts files from Sort to Keyed format (so that a ProvideX data dictionary may be embedded). Checkbox indicating that DOS characters are to be replaced with Windows characters. Do not set this option if you know your data contains either binary or high-ascii (umlaut) data. Program Options The options available in this sub-folder are outlined below: Oem to Ansi conversion in programs Add '-' in front of 'window' title Checkbox indicating that the converter is to replace DOS characters with Windows characters. Checkbox indicating that ProvideX is to insert a '-' character in front of a window title so that the title position is compatible with BBx (this to prevent misalignment with data in the window). Copyright 2009 Sage Software Canada Back 8

9 BBx Conversion Prefix reserved variables with the prefix Variable prefix Remove BBx ERR=20 from source pgm Program specifics Checkbox indicating that GUI_CV is to prefix all BBx program variables that are conflicting with ProvideX system variables and/or functions with a prefix of your choice (see below). By default, the converter will put BB in front of the variable name. For example, 0010 LET RET=99 will become 0010 LET BB RET=99. Variable prefix to be used (see above). Checkbox to avoid ERR=20. BBx program code that has a syntax error in the BBx environment will result in a ProvideX line of code that still has a syntax error on it. By selecting this option, GUI_CV will re-compile the line with the error that could result in a correct line of code in the ProvideX environment. For example, this line of BBx code: 0010 *ERR msgbox a$,"hallo","!,cancel",b$ will convert to ProvideX: 0010?**ERR= msgbox a$,"hallo","!,cancel",b$ when this option is not selected. Setting this option will result in the ProvideX code: 0010 MSGBOX A$,"Hallo","!,CANCEL",B$ List of checkboxes for defining program specifics. These options are described below. Use $0A$ in Direct/Mkeyed/Indexed ProvideX normally creates files that use field separator $8A$. By selecting this setting, the BBx file creation verbs Direct, MKeyed and Indexed will be changed to include the,sep=$0a$ file option to force creating files that use the $0A$ separator. Also check the Create files with $0A$ separator setting under the File Options tab to convert BBx files to ProvideX files with a $0A$ separator. CISAM -> CREATE TABLE Replace all occurrences of CISAM with CREATE TABLE. INFO() -> FN%INFO$( ) Replace the BBx INFO( ) function with the global ProvideX defined function FN%INFO$( ). This function can be found in the *conv.bbx/start_up program along with a number of other settings that you might want to use after converting a BBx application. REV -> FN%REV$ Replace the BBx REV system variable with the global ProvideX defined function FN%REV$. This function can be found in the *conv.bbx/start_up program (feel free to change that function to return whatever your BBx application expects). Copyright 2009 Sage Software Canada Back 9

10 BBx Conversion SSN -> FN%SSN$ Replace the BBx SSN system variable with the global ProvideX defined function FN%SSN$. This function can be found in the *conv.bbx/start_up program (feel free to change that function to return whatever your BBx application expects). SYS -> FN%SYS$ Replace the BBx SYS system variable with the global ProvideX defined function FN%SYS$. This function can be found in the *conv.bbx/start_up program (feel free to change that function to return whatever your BBx application expects). 'ATTR'() -> FN%ATTR$( ) The 'ATTR' mnemonic will be replaced by the ProvideX 'MODE' mnemonic which isn't fully BBx compatible. By selecting this option, ProvideX will use the global defined function FN%ATTR$( ) instead, which should result in BBx compatible output. This function can be found the *conv.bbx/start_up program. 'RGB'() -> FN%RGB$( ) The 'RGB' mnemonic will be replaced by the ProvideX 'MODE' mnemonic which isn't fully BBx compatible. By selecting this option, ProvideX will use the global defined function FN%RGB$( ) instead which should result in BBx compatible output. This function can be found the *conv.bbx/start_up program. BBx Conversion, Character-Based Below are some of the steps required to convert an existing BBx application to ProvideX. The tool kits described consists of several programs that perform two separate functions. The first group of routines convert the programs and data from BBx to ProvideX. The second group includes a collection of public program replacements for common utilities supplied with BBx. Running the Conversion ProvideX should be installed on the same network or system where BBx resides. Also, your backups should be up to date. If you do not have recent verified backups of your target programs and data, please produce these backups before proceeding any further. There are slightly different starting instructions for Windows and UNIX. To start the conversion, type the following based on the platform which best matches the environment being converted: UNIX-based systems: cd /pvx/lib/_conv.bbx./bbx2pvx Windows-based systems: Run ProvideX, then type the following at the command line: cwdir "/pvx/lib/_conv.bbx" run "cv" Copyright 2009 Sage Software Canada Back 10

11 BBx Conversion The first screen of the conversion routine appears similar to the following: Conversion Checkout Only...: Y This feature allows you to step through the entire conversion process to produce an exception report in advance without actually converting any of the programs or files. The exception report can then be analyzed to determine if there will be any compatibility issues. Full path to BBX executive...: C:/BBx/BBx/bbx4.exe During the conversion, BBx is called on to translate the files & programs. It stores them in a flat file which ProvideX reads from. The BBx executive must exist for the conversion to run. Full path to config.bbx file...: C:/BBx/BBx/config.bbx This indicates the location of the config.bbx file. VARIABLE length record files...: Y This question should always be answered Yes. ProvideX will create all of the Keyed files using variable length record which will reduce disk space requirements and increase file performance. Eliminate Max record counts...: Y Answering Yes will create all Keyed files with no preset limit to the number of records in a file. Copyright 2009 Sage Software Canada Back 11

12 BBx Conversion Megabytes of available disk space.: 4 Minimum amount of disk space required is equal to the size of the largest BBx file. If you plan to maintain both BBx & ProvideX systems then you will have to have as much disk space available as the BBx system currently occupies. If you are not overwriting the existing BBx application, you must first reduce the amount of free space by the size of the BBx application. Input File/Directory...: C:\bbx\bbx Directory representing the parent directory for the programs & data files. Output File/Directory...: C:/tem2 The output directory can either be the same as the input directory or a different directory. If you specify different directories, the BBx programs & files are left untouched after the conversion. If input & output directories are the same, the BBx files & programs are erased after they are converted. If disk space is limited, you may have to specify the same directory for both input & output. Conversion LOG file...: C:\temp1.log This log file is useful to determine the overall status of the conversion. It is a flat ASCII file which can be accessed with any text editor or word processor. The log will contain any error or warning messages generated by the conversion. It can also provide a complete list of all files & programs converted. Log errors only...: Y Controls the type of information stored in the Conversion LOG file. If you answer Yes, the log will only contain Error & Warning messages which require attention. Answering No will list every file & program which was run through the conversion along with the error & warning messages. Convert SORT files to KEYED files.: Y Converts files from Sort to Keyed format (so that a ProvideX data dictionary may be embedded). Programs Included with Tool Kit The programs supplied with the tool kit are outlined below: Conversion Programs: cv cv-bbx _bbx2pvx.bbx _bbxcvin _getcnfg BBx Conversion - Main Routine BBx Conversion - Execute BBx translator BBx Program to block files into String/Serial files BBx Import Facility - Read in blocked serial files Get BBx Configuration Information Copyright 2009 Sage Software Canada Back 12

13 BBx Conversion Public Program Replacements & Run Time Routines: set_opts START_UP _calc _cdir.pub _cdisk.pub _clear.pub _cpfx.pub _cpubs.pub _cwindow.pub _expand.pub _getdevs _help.pub _outsel.pub _path.pub _popup.pub _prntsel.pub _scall.pub _setup _stdinp.pub _stdsel.pub _timday Set Default BBx OPTS String Standard BBx Compatibility Mode Startup ProvideX built-in calculator Change current Directory Change current Drive Clear Display & Public Programs Change Prefix Drop all Public Programs Clear all Windows Expand a file on the fly Get Devices/Configuration information during start up Help utility Select Output Device Separate Drive, Directory & File Name Create a window Select Printer Perform a System Call Dummy colour setup Standard Input Standard Input - Selection Bar Set the Current Time & Day What To Do After The Conversion The first step after the conversion is to analyze the error log file. It will contain a list of items which should be checked. Some of the these warning messages are explained below: Warning: Possible $0A$ This warning should be checked carefully. BBx uses $0A$ field separators where ProvideX uses $8A$. For portability, we recommend using the System Variable SEP. These messages show up frequently for Indexed files that are not initialized. It is also produced for any occurrence of the text 0A, not just Hex strings. Error: Compile errors will list the statement & the associated error message If a statement cannot be compiled, it will be listed with a description of the error. One possible cause could be the use of a reserved word as a variable name. Warning: KEYED file is using Unique Key feature (file name) ProvideX supports the unique key feature on the primary (external) key only. Copyright 2009 Sage Software Canada Back 13

14 BBx Conversion How to Start the New Application BBx Emulation ProvideX uses a program called START_UP to setup and configure the working environment. There is a standard BBx emulation mode START_UP program in the BBx conversion directory. This program should be copied to your applications data directory. Launching ProvideX from your applications data directory will then start in BBx emulation mode. ProvideX has several parameters and mnemonics used to emulate some of the non-standard BBx functionality. These parameters are designed to simplify the transition from BBx to ProvideX. In most cases it is desirable to modify your programs to run in native ProvideX mode. BBx emulation is accomplished by setting the BX parameter and printing the SX menmonic. The following outlines what happens when the 'BX' parameter is enabled: Enables BBx Compatibility Mode (see below). Enables'XF' parameter which extends files number to Enables'CD' parameter which cause PVX to search current directory first. Enables'RR' parameter (ERR reset on RUN). Enables'OP' parameter which maintains file names as originally given. Enables'WK' parameter which causes windows drop to DROP on END Enables'QS' parameter which causes START to basically invoke a RUN. Enables'DC' parameter which causes spaces to be output Enables BT parameter which tests first read to switch to binary file access (ISZ=). Enables EX parameter which causes EXECUTE to effect program at level 0. Enables NK parameter which causes Null key stripping. Enables NR parameter which won t allow intermediate rounding on divides. Enables RS parameter which causes round STR( ) function. Sets the FID format to 3 (BBx format). Sets the Julian date base year to 0 (Julian calendar). BBx compatibility mode. This changes the way ProvideX processes some command and functions; i.e., TCB(15) Returns the number of 256 bytes block of memory instead of total bytes TCB(13) Program levels are base 0 during BBx mode (normally base 1). Windows Window numbers are base 0 during BBx mode (normally base 1). The main window (0 in compatibility mode) cannot be dropped. Copyright 2009 Sage Software Canada Back 14

15 BBx Conversion KEP( ) KGN( ) Termina I/O 'TR' The KEP( ) function returns the key of the record just read The KGN( ) function will expect a BBx compatible key definition A READ RECORD (0,SIZ=1)... will return the following: CTL1=$1C$, CTL2=$1D$, CTL3=$1E$, CTL4=$1F$, Down=$0A$, Left=$08$, Up=$0B$, Right=$0C$ This reads the screen contents not the window contents START The size parameter will be considered a 256 byte blocks not 1024 byte blocks. EXECUTE KNO Serial I/O TIM This will alter the mainline program, not the current program. The current KNO will not be remembered in compatibility mode If first I/O to a Serial file uses a RECORD clause and a SIZ=option, the file will be switched from serial to Binary (ISZ=-1). The time variable will be rounded to the current precision. The following are the differences in terminal output caused by the 'SX' mnemonic. When the 'SX' mnemonic is issued the following occurs: 'RM' 'CL'/'CE'/'CS' All output 'attributes' are reset (Blink, Reverse, Background). Normally, output is reset to the current default colour/attributes All output attributes are reset and the region is cleared with the default colour as opposed to clearing to the current background colour. Note: While it is possible to run for an extended period of time using the 'BX' parameter and 'SX' mnemonic, there is no guarantee that these will continue to provide compatibility with future BBx versions. In addition, there are some minor performance penalties inherent with the use of these options. Copyright 2009 Sage Software Canada Back 15

16 BBx Conversion Direct Translation from BBx The following BBx directives/functions can be directly translated to ProvideX BBx ProvideX ARGV( ) ARG( ) CHDIR CWDIR DATE( ) DTE( ) FILL( ) DIM( ) INITFILE REFILE KEYF( ) KEF( ) KEYL( ) KEL( ) KEYP( ) KEP( ) KEYN( ) KEN( ) KGEN( ) KGN( ) MASK( ) MSK( ) MKEYED KEYED RENUM RENUMBER SCALL( ) SYS( ) SWAP( ) SWP( ) STRING SERIAL DREAD READ DATA 'RGB' 'MODE' 'ATTR' 'MODE', KNUM =, KNO =, MODE =, OPT = STBL( ) GBL( ) FIELD VIA FIELD( ) VIS( ) NFIELD( ) VIN( ) FATTR( ) XFA( ) FNERR ESCAPE INFO(0,0) SID INFO(3,0) GID INFO(3,2) WHO INFO(3,3) UID INFO(3,4) NID INFO(4,) ENV( ) FNEND END DEF MKDIR DIRECTORY RMDIR ERASE Copyright 2009 Sage Software Canada Back 16

17 BBx Conversion FBIN( ) I3E( ) FDEC( ) I3E( ) SSORT( ) SRT( ) ROUND( ) PRC( ) 'TITLE' 'CAPTION'!( ) NOT( ) ProvideX also provides three different FID formats: 0 - ProvideX standard 1- Thoroughbred format 2- Rexon format 3- BBx format Copyright 2009 Sage Software Canada Back 17

18 Open BASIC Conversion Open BASIC Conversion Open Basic Conversion BMK Converting Program Files This section outlines the steps required to convert to the ProvideX language from Open BASIC. The tool kit consists of three programs which convert programs and data files from Open BASIC to ProvideX. ProvideX should be installed on the same network or system where Open Basic resides. Also, your backups should be up to date. If you do not have recent verified backups of your target programs and data, please produce these backups before proceeding any further. Step 1. Build the oputput file in Open Basic: START 512 OPEN (1)"/pvx/lib/_conv.ob/bundlob.asc" MERGE (1) END RUN Step 2. You will be prompted with the following questions: Input directory (C:/USR/OB/BIN): Enter the name of the directory that contains the Open Basic programs. Output Text File name: Enter the name of a flat text file that will be created and used to store a text image of the programs. The conversion program will then search the input directory and any subdirectories for Open Basic programs. Each program found will be added to the output file in text format. Step 3. Exit Open Basic. Step 4. Execute the following in ProvideX: RUN "/pvx/lib/_conv.ob/unbundle.ob Step 5. You will be prompted with the following questions: Name of bundle file to convert: Enter the name of the Output Text File created in Step 2. Name of log file (if desired): The name of a flat text file which will list any errors detected Output Directory: The directory where the converted ProvideX programs will be stored Step 6. After the conversion has finished, inspect the log file and make any necessary changes. Copyright 2009 Sage Software Canada Back 18

19 Open BASIC Conversion Converting Data Files Step 1. Execute the following in ProvideX: RUN "/pvx/lib/_conv.ob/cvdata.ob Step 2. You will be prompted with the following questions: Starting OBASIC directory: Enter the name of the directory which contains the Open Basic data files Output ProvideX Directory: Enter the name of directory where the converted ProvideX data files will be stored. Copyright 2009 Sage Software Canada Back 19

20 Thoroughbred Conversion Thoroughbred Conversion Thorourghbred Conversion BM K This section outlines the steps required to convert to the ProvideX language from ThoroughbredBASIC. ProvideX should be installed on the same network or system where Thoroughbred BASIC resides. Also, your backups should be up to date. If you do not have recent verified backups of your target programs and data, please produce these backups before proceeding any further. Converting Program and Data Files (Direct, Indexed, Msort and Sort) Step 1. Build the output file in Thoroughbred: Merge in the program file "/pvx/lib/_conv.tbd/bundltbd.asc" END RUN Step 2 - You will be prompted with the following questions: Input directory: Enter the name of the directory that contains the Thoroughbred programs and data files. Output File: Enter the name of a flat text file that will be created and used to store a text image of the programs and data. The file will be stored in the directory associated with "DEV D0". The conversion program will then search the input directory and any subdirectories for Thoroughbred files. Each program or file found will be added to the output file in text format. Step 3. Exit Thoroughbred Step 4. Execute the following in ProvideX: RUN "/pvx/lib/_conv.tbd/unbundle.tbd" Step 5. You will be prompted with the following questions: Name of bundle file to convert: Enter the name of the Output Text File created in Step 2. Name of log file (if desired): The name of a flat text file which will list any errors detected Output Prefix: The directory where the converted ProvideX programs will be stored Step 6. After the conversion has finished, inspect the log file and make any necessary changes. Copyright 2009 Sage Software Canada Back 20

21 Thoroughbred Conversion Converting Data Files Step 1. Execute the following in ProvideX: RUN "/pvx/lib/_conv.tbd/convdata.tbd" Step 2. You will be prompted with the following questions: Name of directory to convert: Enter the name of the directory that contains the Thoroughbred data files. Output Directory: Enter the name of the directory where the converted ProvideX data files will be stored. Copyright 2009 Sage Software Canada Back 21

22 MicroShare Conversion MicroShare Conversion MicroShar e Basic Conversion BMK Converting Program Files This section outlines the steps required to convert to the ProvideX language from MicroShare BASIC. Special thanks to Young Systems for providing the foundation for these conversion routines. ProvideX should be installed on the same network or system where MicroShare BASIC resides. Also, your backups should be up to date. If you do not have recent verified backups of your target programs and data, please produce these backups before proceeding any further. Step 1. Build the output file. Create a flat text file called PROGLIST in MicroShare's Directory 0 that contains a list of the program names to convert. If the programs are in a directory that is not enabled, enable the directory, making sure the correct copies of the programs to convert are accessed first. Step 2. From the MicroShare prompt, load the program conversion routine. DELETE OPEN(1)"/pvx/lib/_conv.msb/pgms2pvx.asc" MERGE(1) END RUN Step 3. Exit MicroShare Step 4. Execute the following in ProvideX: RUN "*conv.msb/asctoprg" Step 5. Follow the prompts. For the input directory, enter the full path of MicroShare's Directory 0. For the output directory, enter the full path of the directory where the resulting ProvideX programs are to reside. Once these steps are complete, the output directory will contain a copy of all of the programs listed in the PROGLIST text file, in ProvideX program format. The results of the conversion should be checked for errors using the ProvideX utility called '*tools/errscn'. The conversion routine compensates for native MicroShare functions by converting them to global ProvideX functions. These functions are provided in a program called '*conv.msb/function.def'. This program must be called from the START_UP program in order for the application to function properly. Copyright 2009 Sage Software Canada Back 22

23 MicroShare Conversion Converting Data Files Step 1. Build the output file. Create a flat text file called FILELIST in MicroShare's Directory 0 that contains a list of the data file names to convert. If the data files are in a directory that is not enabled, enable the directory, making sure the correct copies of the data files to convert are accessed first. Step 2. From the MicroShare prompt, load the data file conversion routine. DELETE OPEN(1)"/pvx/lib/_conv.msb/dat2pvx.asc" MERGE(1) END RUN Step 3. Exit MicroShare Step 4. Execute the following in ProvideX: "*conv.msb/cnvdat" Step 5. Follow the prompts. For the input directory, enter the full path of MicroShare's Directory 0. For the output directory, enter the full path of the directory where the resulting ProvideX data files are to reside. Once these steps are complete, the output directory will contain a copy of all of the data files listed in the FILELIST text file, in ProvideX format. Copyright 2009 Sage Software Canada Back 23

24 Syntax Unique to ProvideX Syntax Unique to ProvideX Syntax U nique to ProvideX BMK For someone who has worked in Basic or Business Basic before, the ProvideX language should be easy to learn. Many instructions used in other Basic systems are also found in ProvideX Basic, but the language does have some unique properties. This section discusses ProvideX language elements that may not be available, or may not provide the same functionality, in other languages. Before writing programs in this language, we suggest that you review the ProvideX Language Reference and the ProvideX User s Guide for complete details on this syntax. CALL/RUN - Allows Definition of a Line Label Entry Point CALL - Allows Passing Arguments by IOLists DAY_FORMAT - Allows Definition of Format of the DAY Variable. DEFCTL - Used to Define CTL Values for Input Termination Sequence DEFTTY - Defines File as a Terminal and Its Screen Size DEFPRT - Defines File as a Printer and Its Page Size DIM - Defines Composite String of Variables in IOLIST ENTER - Extended to Allow IOLists in Argument Definitions ENTER - Value Not Passed Back When Variable Surrounded by ( ) ERROR_HANDLER - Defines Application Wide Error Handler Program. ESCAPE - Generates Error Code Specified 25 EXECUTE - Modifies Code at all Levels (Modifies Current Level by Default) IOLIST - IOLists Contain Record Formatting Rules IOLIST - IOLists Assigned to Variables. LINE_SWITCH - Re-Routes file #0 I/O to Specified File LOCAL - Indicate Local Variables MERGE - Merges from Named file (Open not required) MESSAGE_LIB - Allows Definition of User Message Library MNEMONIC - Used to Define Terminal/Printer Mnemonics NEXT - Variable Name not Required OBTAIN - Same as INPUT (Without Echo) OPEN - Allows for LOCK/PURGE/INPUT/LOAD options OPEN - Multiple Opens Strung Together PASSWORD - Encrypts Program and Prevents Listing/Editing PERFORM - Similar to CALL, Variables Shared with PERFORMed Program... PREFIX - No Size Limit, Extended Functionality... PREINPUT - Allows Placement of Data into Input Queue PURGE - Erases all Data from File Specified (if Locked) READ DATA FROM - Extracts Data from String, Processes Against IOList SETESC ON OFF - Enables/Disables ESCAPE/BREAK Key Recognition SETESC ENABLE DISABLE - Enables/Disables Processing of SETESC #### SETCTL - Defines Automatic GOSUB to Process CTL Events SETFID - Change FID of Open Channel SETMOUSE - Control Mouse Events and Processing Logic SWITCH..CASE - Allows Conditional Logic on Either Numeric or String Value TRANSLATE - Translates Data Using Translation Table USER_LEX - Allows Redefinition of ProvideX Directives, Functions and Variables VIA - Indirect Variable Assignment Copyright 2009 Sage Software Canada Back 24

25 Syntax Unique to ProvideX CALL/RUN - Allows Definition of a Line Label Entry Point When specifying a program name, you can suffix it with a semi-colon and the starting label within the program. CALL "PROG01;Add_Record",X$,Y$ In PROG REM PROG INIT: 0030 OPEN (1) "ARCUST",(2) "ARBILL" 0040 EXIT 0100! Add-record logic 0110 ADD_RECORD: 0120 ENTER CST_ID$,CST_NAME$ 0130 WRITE (1) CST_ID$, CST_NAME$ 0140 EXIT The CALL "PROG01:Add_record" will cause the system to call program PROG01, but rather than start execution at the start of the program it will commence at the label ADD_RECORD. This feature allows for the creation of programs that become libraries of functions. It simplifies programming and maintenance as you can create Modular libraries for specific files, functions, etc. CALL - Allows Passing Arguments by IOLists The CALL directive supports the use of an IOL=nnnn to pass variables CALL "PROG01;Add_record", IOL= IOLIST X$,Y$ DAY_FORMAT "fmt_string" - Allows Definition of Format of the DAY Variable The DAY variable can be defined through the use of Y, D, M and A characters in the string passed to this directive. The DTE( ) and JUL( ) functions also support the AA format mask. For July DAY_FORMAT "MM/DD/YY "DAY = "07/04/02 "<- Default DAY_FORMAT "DD/MM/YY "DAY = "04/07/02" DAY_FORMAT "YY/MM/DD "DAY = "02/07/04" DAY_FORMAT "AA/MM/DD "DAY = "A2/07/04" Copyright 2009 Sage Software Canada Back 25

26 Syntax Unique to ProvideX DAY_FORMAT "YYYY/MM/DD "DAY = "2002/07/04" DAY_FORMAT "YYYY-MM-DD "DAY = " " DAY_FORMAT "YYYY MM DD "DAY = " " DEFCTL - Used to Define CTL Values for Input Termination Sequence See section on INPUT HANDLING. DEFTTY (chan) col, line - Defines File as a Terminal and Its Screen Size DEFPRT (chan) col, line - Defines File as a Printer and Its Page Size These two directives are used to define the default width and height of the terminal/printer open on the file specified. The functions MXC( ) and MXL( ) can be used to determine the maximum columns and& lines addressable on a channel. Using the DEFPRT also allows the use of both columns and rows for Row) positioning on printers. The Row positioning for printers is forward-minded for text mode printing. Issuing a PRINT (chan)@(0,10) will advance to row 10 if the printer is currently on row 6. It will issue a form feed and advance to row 10 if the printer is currently on row 12. DIM var:iol=iolist - Defines Composite String of Variables in IOLIST *** COMPOSITE STRINGS *** You can create composite strings through the use of the DIM directive. A composite string is a string that is defined by an IOList and will be automatically generated by the system whenever the variable is referenced, and parsed whenever it is changed IOLIST NAME$, ADDR$, OWING 0100 DIM CST$:IOL=0010 Defines CST$ as being comprised of CST.NAME$, CST.ADDR$, and CST.OWING each separated by a field separator ($8A$). Whenever CST$ is referenced, it will be dynamically created. Whenever CST$ is changed, the data will be parsed and placed into the corresponding variables. Composite strings can, in most cases, be used to replace BBx string templates; however, because of their entirely different implementation it is important to note that: 1. Fields in composite string are TRUE variables and, as such, are passed to subprograms by reference rather than by value. 2. Access times to the variables is faster, but access to the whole variable is slower You can also use BBx style string template definitions such as: DIM CST:"name:C(*),addr:C(*), owing:n(*)" Copyright 2009 Sage Software Canada Back 26

27 Syntax Unique to ProvideX ENTER arg, IOL=IOList - Extended to Allow IOLists in Argument Definitions The ENTER directive (like the CALL directive) can also use an IOList to define the variables. CALL "PROG01;Add_Record",X$,Y$ In PROG ! Add-record logic 0110 ADD_RECORD: 0120 ENTER IOL= WRITE (1) CST_ID$, CST_NAME$ 0140 EXIT IOLIST CST_ID$,CST_NAME$ ENTER arg, (arg) - Value Not Passed Back When Variable Surrounded by ( ) If a called subprogram does not want to pass back a changed value, it can surround any variable with ( ). This capability also exists on CALL statements IOLIST (CST_ID$), CST_NAME$ ERROR_HANDLER - Defines Application Wide Error Handler Program The ERROR_HANDLER directive allows the user to define a generic handler to be invoked whenever an un-trapped error is detected within a program. When an error occurs within a program that is not handled either via an ERR= or SETERR directive, the system will internally call the ERROR_HANDLER program. This program may then take any corrective action desired and return to the offending instruction via the EXIT directive. If an EXIT ERR directive is used to return from the ERROR_HANDLER, the normal error processor is invoked, thus potentially returning to command mode. If no program name string is provided, the current error handler is canceled. The error handler program remains in effect until a START directive is executed. A sample program called *ERROR can be used as a template for creating an error handler routine. Copyright 2009 Sage Software Canada Back 27

28 Syntax Unique to ProvideX ESCAPE nnn - Generates Error Code Specified The ESCAPE directive can be used to generate an error within a multi-line function DEF FNCHK_VAL( Z) 0020 IF Z<0 ESCAPE IF Z>100 ESCAPE S=INT(SQR( Z)) 0050 IF S * S <> Z ESCAPE RETURN Z 0070 END DEF EXECUTE - Modifies Code at all Levels (Modifies Current Level by Default) Unlike many other Business Basics, the EXECUTE directive will affect the current program by default unless the 'EX' parameter is set. IOLIST - IOLists Contain Record Formatting Rules In addition to simply naming the variables that are to be used in a READ of WRITE directive, an IOList can also define the exact format of a data record. A format specification may be given immediately following the variable names on an IOLIST directive. The format specification is used to define the exact size and form that the data has on the file record. Format specifications should be separated from the variable name by a : colon and enclosed within [ ] square brackets. The following are currently supported format specifications: CHR(len) CHR(dlm) LEN(len) STR(dlm) NUM(len,scl) SGN(len,scl) BIN(len,scl) INT(len,scl) BCD(len,scl) Variable length string (fixed output or delimited) Variable length string (delimited) Fixed length string Quoted string Fixed length numeric Signed fixed length numeric Binary numeric Unsigned integer numeric Packed decimal numeric len and scl are numeric values. dlm is a one-character delimiter. In the following example, the IOList on line 1000 would be used for a 60 character record, with the field NAME in positions 1-30 and ADDR1 in positions 31-60: 1000 IOLIST NAME$:[CHR(30)],ADDR1$:[CHR(30)] 1010 IOLIST CUST$:[STR(",")],AMNT:[STR(",")], 1010:DUEDT$:[STR("")] Copyright 2009 Sage Software Canada Back 28

29 Syntax Unique to ProvideX No delimiter would exist between the fields. In line 1010, the IOList would be used against a comma-delimited file where the string values would be enclosed in quotes. IOLIST - IOLists Assigned to Variables ProvideX allows you pass IOLists as variables and use variables as IOLists. In order to utilize a variable as an IOList, it must first be initialized with the object code for the desired IOList. This can be accomplished via the CPL( ) or PGM( ) functions IOL_1$=CPL("IOLIST A$,B$,D") or IOL_1$=PGM(1000) 1000 IOLIST A$,B$,D Once a variable has been loaded with the IOList, it may be specified following the IOL= option rather than a line number or statement name. Examples: READ (1) IOL=IOL_1$ One nice feature is the ability to combine variable IOLists with the ability to use IOLists in CALL/ENTER. The following uses the function TCB(4) to get the current line number, then add 1. When this is passed to the PGM( ) function, the contents of the next line will be returned, which should have the desired IOList. This type of coding will not be affected by the RENUMBER directive _Z$=PGM(TCB(4)+1); CALL "PROG",_Z$,IOL=_Z$ 0101 IOLIST CST_ID$,CST_NM$ In PROG ENTER _Z$, IOL=_Z$ LINE_SWITCH file - Re-Routes file #0 I/O to Specified File In order to provide for a remote maintenance mode of operation, the LINE_SWITCH directive will switch file OPEN (1,OPT="9600,n,8,1") "COM2"! Open comm port 0020 CALL "*dev/ansi"! Load Ansi device driver 0030 LINE_SWITCH (1) or... assuming T2 is defined as COM2, simply LINE_SWITCH "T2" This can be used on a Windows system to provide for dial-in access. This directive also provides a foundation for the client/server capabilities of ProvideX on a Windows network using WindX. Copyright 2009 Sage Software Canada Back 29

30 Syntax Unique to ProvideX LOCAL varlist - Indicate Local Variables The LOCAL directive allows a program to temporarily reassign a variable without affecting the original contents. If the variable name is currently in use, the system will preserve the current value of any of the variables mentioned with the LOCAL directive. Once the stack has been terminated, the system will restore the variables to their original values. DEF FNXYZ(LOCAL X, LOCAL Y, LOCAL Z)=X+Y+Z FOR LOCAL X=1 TO 100 Variables are active until current FOR / GOSUB stack is terminated or program exits. MERGE "file" - Merges from Named file (Open not required) This merges directly from a Serial or Indexed file without having to open the file first. MESSAGE_LIB - Allows Definition of User Message Library The MESSAGE_LIB directive in conjunction with the MSG( ) function is used to define and access a message library. Each message in the library must contain a key and text. The text may contain up to 36 parameters designated %0, %1, %2, up to %Z. When referencing the message via the MSG( ) function, the parameters may be placed in the MSG( ) function. %0, always contains the message key. A message library must be a variable length Direct file with the key being the message identifier. The record contains the message. MSGLIB.EN is a direct file with the following record: Key: NOCUSTData: "Sorry but customer %1 does not exist: 0010 MESSAGE_LIB "MSGLIB."+ENV("LANG") 1000 READ (CST_FN,KEY=K$,DOM=1900) PRINT MSG("NOCUST",K$) MNEMONIC - Used to Define Terminal/Printer Mnemonics The MNEMONIC directive allows the user to define additional mnemonics for files and/or devices. Once defined, each mnemonic remains active for the file until the file is closed. When the defined mnemonic is encountered in a PRINT or INPUT statement the system converts the mnemonic to the character string specified OPEN (1)"/dev/printerxx" 0020 MNEMONIC (1) 'US'=ESC+"_" Define mnemonic PRINT (1)'US',"Title line...", Copyright 2009 Sage Software Canada Back 30

31 Syntax Unique to ProvideX NEXT - Variable Name not Required Specifying a variable name on a NEXT is supported but not required. OBTAIN - Same as INPUT (Without Echo) An OBTAIN can be used accept data from the keyboard without displaying the results on the screen. The OBTAIN is functionally equivalent to doing an INPUT 'EE',X$,'BE'. It can also be used to replace the technique of opening FID(0) on an alternate channel & issuing an INPUT on that channel. OPEN - Allows for OPEN LOCK/PURGE/INPUT/LOAD The following options are available for the OPEN directive: OPEN LOCK (n) "..." Open and attempts to lock the file. If the lock is not successful the open fails and an error #0 is generated. OPEN PURGE (n) "..." Open and attempts to lock the file and purge it contents. If the lock is not successful the open fails and an error #0 is generated. OPEN INPUT (n) "..." Open the file for INPUT only. Any attempt to write to the file will result in an Err #13. OPEN LOAD (n) "..." Open the file in INPUT mode only. All reads against the file will attempt to buffer the data returned in memory with no regard as to concurrent updates by other tasks. Allows extremely fast access to the file. The default for the maximum # of Buffers is stored in the 'OL' system parameter OPEN - Multiple Opens Strung Together The syntax of the OPEN has been expanded to allow: OPEN (1) "file1", (2) "file2", (3) "file3" PASSWORD - Encrypts Program and Prevents Listing/Editing The PASSWORD directive allows the assigning and removal of passwords for ProvideX programs. Passworded programs may not be listed or edited in any way without first removing the password. To assign a password simply load the program, enter the PASSWORD directive followed by the desired password, and then save the program on a PROGRAM file. To temporarily remove a password to allow for program editing and listing, simply reload the program, enter a PASSWORD directive followed by the password Copyright 2009 Sage Software Canada Back 31

32 Syntax Unique to ProvideX previously entered. You can now change the password by entering a different string on a PASSWORD directive then saving the program. To remove the password, change the password to a null string and re-save. If the password string is preceded by an * asterisk, the PASSWORD directive defines a common password which will be automatically applied to all passworded programs as they are loaded and assigned to all new programs. PERFORM - Similar to CALL, Variables Shared with PERFORMed Program... A PERFORM can be considered an external GOSUB. That is, all the variables are passed to a PERFORMed program. If a PERFORMed program issues a RETURN with the GOSUB stack empty, it will be considered EXIT. 0010! CUSTOMER - Customer logic GOSUB CHK_TYPE ! Validate customer number 1010 CHK_TYPE: ERR_MSG$="" 1020 IF POS(CST_TYPE$=%CST_TYPE_TBL$)=0 ERR_MSG$="Bad Type" 1030 RETURN In another program PERFORM "CUSTOMER;Chk_type" 1010 IF ERR_MSG$<>"" GOTO PREFIX - No Size Limit, Extended Functionality... The ProvideX environment provides the ability to emulate up to 10 disk drives through the use of the PREFIX directive. Internally, ProvideX maintains 10 different prefix strings where each may be considered a logical disk drive (#'s 0 through 9). In order to define each of these strings the PREFIX directive has been extended to: PREFIX (driveno) "prefix_string" When searching for a file, ProvideX will check each of the logical drive prefixes sequentially. Individual PREFIX entries may be removed from the search via the DISABLE directive. The current value of each of these prefixes may be obtained via the PFX(num) function. A special prefix may be defined specifically for use when accessing programs: PREFIX PROGRAM "prefix_string" Copyright 2009 Sage Software Canada Back 32

33 Syntax Unique to ProvideX Once a program prefix is defined, it will be the first prefix used for all LOAD, RUN, CALL, PERFORM, PROGRAM and SAVE commands. Only after the program prefix has been searched will the other prefixes be checked. All other file accesses will search the other prefixes first, then the program prefix. Use PFX(PGN) to obtain the current setting of the program prefix. In many systems the file names are standardized; i.e., the leading 2 or 3 characters indicate the subsystem or application that the program/file belongs to. For example 'ARHIST' or 'ARINFO' might belong to the Accounts Receivable subsystem. The PREFIX directive allows for the automatic separation of these files based on the first characters. Substituting the = equals sign character in the PREFIX directive causes ProvideX to take the first character of the file name. Each character of the file name that corresponds by position to an equals sign will be used to form a subdirectory name to be used in the search. For instance, if you include 1 equals sign, ProvideX will interpret that to mean that the first character of filename$ is also the subdirectory name. If you include 2 equals signs, it will take the first 2 characters as matching the subdirectory name, and so on. Refer to the ProvideX User s Guide for examples. The PREFIX FILE format provides the ability to dynamically translate file name references using a Keyed file as a lookup table. The Keyed file established with the PREFIX FILE is searched using the referenced file name as the key. The actual file name to be substituted is stored in the record area for this key. The Keyed file specified as a PREFIX FILE must be a variable length keyed file. The normal PREFIX search rules still apply after a file name has been located in the PREFIX FILE Keyed file. KEYED "PFX",10 OPEN (1) "PFX" WRITE (1,KEY="CUSTDB") "[odb]my_database;customer;key=custid" CLOSE (1) PREFIX FILE "PFX" OPEN (1) "CUSTDB" This opens the ODBC database My_database, table Customer. Normally, ProvideX checks the current directory after having searched all other prefix entries. The system parameter 'CD' can be set to force ProvideX to check the current directory first. PREINPUT - Allows Placement of Data into Input Queue The PREINPUT directive allows the program to prime the input buffer for the user terminal with a string value and an optional CTL value. Multiple PREINPUT directives can be issued with the messages queued such that the first PREINPUT data will be processed first (FIFO) unless a PREINPUT NEXT option is specified. Copyright 2009 Sage Software Canada Back 33