4glref.doc

4GL Reference ManualPRONTO-RAD (Rapid Application Development) is a fully integrated fourth generation language facility which enables you to generate applications, ranging from the simplest to the most complex, with a minimum of time and effort. PRONTO-RAD incorporates the following features:  Data dictionary (database) generation and maintenance.  4GL - The fourth generation language that most PRONTO-Xi applications are written in.  SQL - A query language facility for general reports and user ad-hoc queries.  LST - The default report generator used with SQL.  RPT - An alternative to LST for more complex reports.  Screen based application generation and maintenance routines.  Interactive program debugging facilities. Version Pronto is a registered trademark and PRONTO-Xi is a trademark of Pronto Software Pty Ltd (ABN 47 001 337 248). This product includes software developed by the Apache Software Foundation (http://www.apache.org). All other products mentioned are trademarks or registered trademarks of their respective companies. Copyright © 2009 Pronto Software Pty Ltd. All rights reserved. Version: 6.7 v1.0 All businesses referred to in examples are entirely fictitious. Any resemblance to any company, or individual, is accidental. Disclaimer: Each manual provides an overview of the functions available for that module based on out-of-the-box settings. Pronto Software does not provide procedural manuals and/or work instructions due to the complex and differing nature of business models PRONTO-Xi currently supports. Permission is granted for information to be copied from the reference manuals for the express purpose of writing site-specific procedures/work instructions. Table of Contents 4GL Reference Manual.................................................................................................................................... 1 Version.......................................................................................................................................................... 1 Organisation of Data..................................................................................................................................... 9 Environment Variables Used for 4GL Programming...................................................................................10 UNIX/Linux Environments....................................................................................................................... 13 Windows Environments........................................................................................................................... 13 Declarations................................................................................................................................................ 14 API Declaration....................................................................................................................................... 14 FIELD Declaration................................................................................................................................... 14 Data Definition Picture Strings............................................................................................................ 16 LOCAL Declaration................................................................................................................................. 17 MENU Declaration.................................................................................................................................. 17 MODE Declaration.................................................................................................................................. 21 1 OBJECT Declaration............................................................................................................................... 24 PARAMETER Declaration....................................................................................................................... 26 PROCEDURE Declaration...................................................................................................................... 27 Row/Object Parameters....................................................................................................................... 30 RETURNING Declaration........................................................................................................................ 31 SCREEN Declaration.............................................................................................................................. 32 Common Clauses....................................................................................................................................... 38 EXPORT Clause...................................................................................................................................... 38 SELECT Clause...................................................................................................................................... 39 Statements.................................................................................................................................................. 45 ABORT Statement................................................................................................................................... 45 ACCEPT Statement................................................................................................................................ 46 ACKNOWLEDGE Statement.................................................................................................................. 53 AUDIT Statement.................................................................................................................................... 53 BACK-TO-DETAIL Statement.................................................................................................................. 54 BEGIN WORK Statement....................................................................................................................... 54 BOX Statement....................................................................................................................................... 54 BOX-CHAR Statement............................................................................................................................ 56 BREAK Statement................................................................................................................................... 56 CALL Statement...................................................................................................................................... 57 CHECK-BOX Statement......................................................................................................................... 58 CLEAR Statement................................................................................................................................... 59 CLOSE Statement................................................................................................................................... 61 COMMAND Statement............................................................................................................................ 61 COMMIT WORK Statement.................................................................................................................... 63 CONFIRM Statement.............................................................................................................................. 63 CONTINUE Statement............................................................................................................................ 65 CONTINUE-ENTRY Statement............................................................................................................... 65 DELETE Statement................................................................................................................................. 65 DISABLE-ALL-TRIGGERS Statement.................................................................................................... 66 DISPLAY Statement................................................................................................................................ 66 DO Statement......................................................................................................................................... 71 END-OPTION Statement........................................................................................................................ 72 END-STATEMENT-GROUP Statement................................................................................................... 72 ENQUIRY Statement............................................................................................................................... 72 EXIT Statement....................................................................................................................................... 73 EXTRACT Statement.............................................................................................................................. 73 FOR Statement....................................................................................................................................... 75 GET Statement....................................................................................................................................... 75 IF Statement........................................................................................................................................... 77 INITIALISE Statement............................................................................................................................. 77 INSERT Statement.................................................................................................................................. 78 2 LINK Statement....................................................................................................................................... 78 LOCK-METHOD Statement.................................................................................................................... 78 MESSAGE Statement............................................................................................................................. 79 MESSAGE-BOX Statement.................................................................................................................... 79 NEED Statement..................................................................................................................................... 81 OPEN Statement..................................................................................................................................... 81 OPTION Statement................................................................................................................................. 83 PAGE Statement..................................................................................................................................... 89 PAUSE Statement................................................................................................................................... 89 POP Statement....................................................................................................................................... 89 POSITION Statement............................................................................................................................. 90 PRINT Statement.................................................................................................................................... 90 PUSH Statement..................................................................................................................................... 92 QUERY Statement.................................................................................................................................. 93 RADIO-BUTTON Statement................................................................................................................... 94 RE-ENTER Statement............................................................................................................................ 95 REFRESH Statement.............................................................................................................................. 95 REPEAT Statement................................................................................................................................. 96 REPORT Statement................................................................................................................................ 96 REPORT SECTION Statement............................................................................................................... 99 RE-SELECT Statement........................................................................................................................... 99 RESTORE Statement............................................................................................................................ 100 ROLLBACK WORK Statement............................................................................................................. 100 SAVE Statement.................................................................................................................................... 100 SELECT Statement............................................................................................................................... 100 SERIAL Statement................................................................................................................................ 101 SET Statement...................................................................................................................................... 102 SKIP Statement..................................................................................................................................... 103 SPL Statement...................................................................................................................................... 104 STATEMENT-GROUP Statement......................................................................................................... 104 STRING Statement............................................................................................................................... 104 SWITCH Statement.............................................................................................................................. 104 TRANSACTION Statement................................................................................................................... 105 UNLOCK Statement.............................................................................................................................. 106 UPDATE Statement............................................................................................................................... 107 VERSION-NUMBER Statement............................................................................................................ 108 WHILE Statement................................................................................................................................. 108 Expressions and Operators....................................................................................................................... 108 Arithmetic Expressions.......................................................................................................................... 108 Alphanumeric Expressions.................................................................................................................... 109 Relational Expressions.......................................................................................................................... 109 Logical (Conditional) Expressions......................................................................................................... 110 3 PRONTO-RAD 4GL Functions.................................................................................................................. 111 Arithmetic Functions.............................................................................................................................. 112 AAND()............................................................................................................................................... 112 ABS()................................................................................................................................................. 112 ANOT()............................................................................................................................................... 113 AOR()................................................................................................................................................. 113 COS()................................................................................................................................................. 113 FRACTION()...................................................................................................................................... 114 GET-SYSTEM-METRICS()................................................................................................................ 114 INTEGER()......................................................................................................................................... 114 LSHIFT()............................................................................................................................................ 115 MAX-VALUE().................................................................................................................................... 116 MIN-VALUE()..................................................................................................................................... 116 POWER-OF()..................................................................................................................................... 116 RANDOM()......................................................................................................................................... 117 RSHIFT()............................................................................................................................................ 117 SIGN-OF().......................................................................................................................................... 117 SIN()................................................................................................................................................... 118 SMALLEST-INCREMENT()................................................................................................................ 119 SQUARE-ROOT().............................................................................................................................. 119 STR()................................................................................................................................................. 119 SUM()................................................................................................................................................ 120 SUM-ARRAY()................................................................................................................................... 120 TAN()................................................................................................................................................. 120 Date Handling Functions....................................................................................................................... 120 ADD-MONTH().................................................................................................................................. 121 DATE-FROM-DATE-TIME()............................................................................................................... 121 DATE-TIME()..................................................................................................................................... 122 DATE-TO-JULIAN()........................................................................................................................... 123 DAY()................................................................................................................................................. 123 DAY-NAME()...................................................................................................................................... 124 DAYS-IN-MONTH()............................................................................................................................ 124 DOW()............................................................................................................................................... 124 HOUR().............................................................................................................................................. 125 JULIAN()............................................................................................................................................ 125 JULIAN-TO-DATE()........................................................................................................................... 125 LEAP-YEAR().................................................................................................................................... 126 MINUTE()........................................................................................................................................... 126 MONTH()........................................................................................................................................... 126 MONTH-NAME()................................................................................................................................ 127 SECOND()......................................................................................................................................... 127 TIME-FROM-DATE-TIME()................................................................................................................ 127 4 ................................... 129 BATCHED().................................................................... 142 FILE-STATUS().............................. 128 ACTIVE-PID()........................... 128 Environment Functions...................................................................................................................... 136 DIARY()..................................... 131 COLOUR-PICKER()..................................................................................... 136 DDE-TERMINATE()........................................................................................................................................................................ 135 DDE-POKE()............................................................................................... 132 CREATE-DB-USER().................................................................................................................................................................................................................. 143 FILE-VERSION().......... 136 ENABLE-SYSTEM-MENU()................................................................................................................................................................................................................................. 147 GET-REGISTRY-ENUM-VALUE()........ 143 FINISH-DIR-SEARCH().................................................................................. 145 GET-PARAM().................................................................................................................................................................................... 137 ENABLE-STATUS-BAR()............................................................................................................................................................................................................................................................................................................ 136 DIR()............................................................................................................................................................... 144 GET-FIELD-VALUE()......................................... 149 5 ..................... 134 DDE-ERROR-STATUS().................................................................................................................................................................................................................................................................................................. 130 CD().................................................................................................................. 131 CD-WITHOUT-CLOSE-ALL().............................................................................................................................................................................. 142 FILE-OWNER().................... 133 DB-COMMAND()...................................................................................................................................................................................... 140 EXIT-STATUS()................................................................................................................................................................................................................................................... 139 ERROR-DESCRIPTION()........ 142 FILE-NAME()...................................................................................................................................................................................... 136 DELETE-REGISTRY-VALUE()............................................. 139 ENABLE-TOOL-BAR()........................................................................................................................................................ 144 GET-FIELD-VALUE-NUMERIC()..................................... 141 FILE-EXISTS()................................................................................................................................. 133 CURRENCY-SIGN().......................................................................................................................................................................................................................................................................................................................................................................................................................................... 135 DDE-REQUEST()..................................................... 132 CREATE-DB-SCHEMA().......YEAR().......................................................................... 144 GET-ENV()....................................................................... 134 DB-TABLE-NAME().................................................................................................................................................................................................................. 135 DDE-INITIATE()........................................................................................................................................................................... 147 GET-REGISTRY-ENUM-KEY()......................................................................................................................................... 135 DDE-EXECUTE()............................................................................................................................................................................................................ 130 CAN-DDE()...................................................................................... 133 DATABASE-TYPE()..................................................................................................................................................................... 139 ESCAPE()............................................................................................... 131 CHECK-AUTH()............................................................................ ..... 157 MESSAGE-STATUS()............. 162 Call an Object Interface................................. 153 LOCAL-DIR()..................................................... 154 MAIL-CANCEL()..................................................................................................................................................................... 159 MOUSE-COLUMN()............................................................................................ 181 6 ........................................................................................................................ 160 Common OLE() Call Parameters................................................. 151 IS-A-DIR()...................... 157 MAX-SCREEN-ROWS().......................................... 156 MAIL-SEND()... 159 MOUSE-ROW()........................................................................ 152 LOCAL-CD-WITHOUT-CLOSE-ALL()..164 Embed an Internet Explorer Window inside a PRONTO-Xi Screen.......................... 158 MODIFICATION-TIME()..........................................................................................................................................................................................165 Excel Code and Functions.............178 OLE-ADDREF()...................................... 150 GMT().......................................................................................................................................................................................................................................................................................................................................................................................................................................... 155 Mail Functions Example........ 151 IF-THEN-ELSE()........................................................................................................................................... 160 OLE Code Examples..................................................................................................................................................................................................... 157 MAX-SCREEN-COLUMNS()..................................................................................................... 154 MAIL-ATTACH()................................................................................................................................170 Populate Data and Create Chart............................................................................................................................................................176 Web Components inside a PRONTO-Xi Screen................................174 Replace Bookmarks and Insert Text into Word Documents....................................................................................................................................................................................................... 153 LOCAL-NO and LOCAL-YES()....................................................................................................................... 152 LOCAL-CD()................................................................................................................. 159 NODE-NAME()............ 155 MAIL-REPLY-TO()............................................................................................................... 158 MODE-NAME()........................................................................................................................................................................................... 153 LOGIN-ID()........................................................................................................................................... 150 GRANT-DB-SCHEMA()................................................. 154 MAIL-FROM-NAME()..................................................................................................................................................................................................... 155 MAIL-START()................................................................................................................................................................................................................................... 150 GID()....................................................................165 Embed a PDF File inside a PRONTO-Xi Screen............171 Populate Excel Spreadsheet and Create Chart.............................................. 158 MKDIR().............................................. 153 MAIL-ADD-LINE()................................................................................................................. 163 Embed a Calendar inside a PRONTO-Xi Screen.................................................................................................................................................................................................................................................... 159 NEXT-DIR-ENTRY()....................................................................................................................................................... 166 Insert Calendar Event or Task into MS Outlook.......................................................................................................................................................................................................................................................................................................GET-REGISTRY-VALUE()..................................................................................................................................................................................................................................................................................................................... ............................................................................................................................................................................................................................................................................................................ 184 OLE-GET-PROPERTY()..................................................................... 185 OLE-QUERY-INTERFACE()......................................................................................................................................................................................................................................................... 185 OLE-RELEASE().................................................................................................................................................... 183 OLE-GET-ACTIVE-OBJECT()................................................................................................................................................... 181 OLE-CALL-INTERACTIVE-METHOD()...................................................... 182 OLE-CALL-METHOD()................ 187 PID()............................ 193 SEARCH()..................................................................................................................... 183 OLE-ENUM-NEXT()................................................................... 184 OLE-PUT-PROPERTY-BYREF()................... 191 REVOKE-DB-SCHEMA()..................................................................................................OLE-ADVISE-EVENT()....... 192 RGB-TO-COLOUR()...... 188 PROUSER-FLAGS()............................ 194 SECURITY-LEVEL().......................................................................... 184 OLE-GET-EVENT()................................................................................................... 186 OLE-UNADVISE-ALL().................................................................................... 195 SET-FUNCTION-CODE()...................................................................................................................................................................................................... 186 PAGE-NO()........... 194 SET-DATA-AREA-NAME()...................................................................................................................................................................................................... 183 OLE-ENUM-RESET()........................................................................................................................... 188 PRONTO-RELEASE()......................................................... 181 OLE-BULK-PUT()........................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................ 185 OLE-STATUS()............................................................ 185 OLE-UNADVISE-EVENT()...................................................................................................................................................... 184 OLE-PUT-PROPERTY()................................................ 183 OLE-ERROR-DESCRIPTION().............................................................. 187 PARAM-CNT()........................................................................................................................................................................................................................................ 182 OLE-CREATE-INSTANCE()............................. 193 SCREEN-MODE()........... 189 REPORT-IS-XML().................................................................................................................................................................................................................................................................................................................................... 182 OLE-CREATE-CONTROL()............................................................................................................................................................................................................................. 195 SET-ENVIRONMENT().......................................................................... 190 REVIEW-ROW()......................................................................... 186 OPERATING-SYSTEM()...................................................................................................................................................................... 194 SET-BACKGROUND-IMAGE()...................................................................................................................................................................................................................................................................................................................................................................... 192 RMDIR()... 193 SEARCH-MODE().. 195 SET-HELP-CONTEXT()................................................................................. 189 REFRESH-QUICK-LINKS().......................................................................................................................................................... 196 SET-MODULE-CODE().................................. 196 7 .............................................................................................................................. 183 OLE-GET-DISPATCH-ID()................................................................................................................. ...................................................................................................................................... 206 LEFT-JUSTIFY()..................................................................................................................................................................................................................................... 197 START-DIR-SEARCH()........................................ 208 OCCURRENCE().................................................................................................................................................................. 216 Pre-Processor Commands Summary.......................................................................................................................................................................... 205 FORMAT-PICTURE()......... 216 8 ................................................................................................................................ 205 FIND-PARAMETER()................................................................................................................ 210 RESERVED()............................................................................................ 212 SIZE-OF()....................................................................................................................................... 203 String Handling Functions....................................................................................................... 207 LINE-NO().................................................................................................................................................................................................................... 197 SLEEP()................................... 199 TIME-ELAPSED()..................................................................................................................................................................................................................................................................... 200 TIME-ZONE().......................... 204 ASCII-CHAR()................... 197 SPOOL-FILE-NAME()................................................................................................... 209 PATTERN()..................................................................................... 201 TTY()............................................ 202 VALID-ACTIVATION-KEY()........................................................................................................................................................................................................................... 212 STR-CONCAT()..................................................................................................................................................................................................................................................................................................................... 214 VALID-NUMBER()..................................................................................... 201 UID().................................................................................................................................................................................................................................................................................................................................................................................................................................................... 204 CONCAT()....................................................................................................................................................................................................................................................................................................................................................................... 208 NUM()............................................................................................................................................................................................................................................................. 215 PRONTO-RAD 4GL Predefined Values.................................................................................................................. 206 FSTR()................................................................................................................................................... 206 IDX().................................... 202 WAIT-FOR-INPUT()..... 202 USER-GROUP().............................................................. 214 Debugger Commands Summary.......... 214 ZSTR()......................................... 208 PARAM-TEXT().................................................. 213 SUB-STRING().............................................................................................................................................................................................................................................................................................. 200 TOD()..........................................................................................................SET-REGISTRY-VALUE()................................................................................................................................................................................................................................................................................................................................... 213 STR-LEN()....................................................................................................................... 198 SYSTIME()........... 201 TODAY()....... 207 LOWERCASE()........................................... 201 TRANSACTION-ACTIVE()..................... 213 UPPERCASE()............................................................................................................................................................................................. 204 ASCII-NUM()................... 211 RIGHT-JUSTIFY()................................................................................ .............. If we wanted to find the record for a particular customer............ would all be fields.... 222 Error Macros......................................... a customer file might contain the name....... then a field is a column within that row.......................................... the customer’s name................... determine how the file is usually going to be accessed. address................................................ then a record can be considered as a single row within that table................... An important point to remember is that each record within a file has the same set of fields....... 224 SQL Server Error Numbers...... multiple indexes can be defined to access the same data in different ways............ For example................................................. state.................................. it would be better to give each customer a unique number or code and then use this as the index. if you search for customers by their surname.......... 226 Organisation of Data The most essential part of designing any application is the definition of the data that will be used........... For example.................... If a record is considered as being a row within the table of information............. Each file can be considered as a table containing information about one type of data... 224 IDS Error Numbers......................... Indexes Although you may have a file with all your data in it...................... Since surnames are not unique (more than one customer can have the same surname).. A database is the collection of data required for your applications.............. PRONTO-Xi uses fields as indexes to allow records to be retrieved efficiently.... 224 PRONTO-RAD 4GL Error Numbers............. 225 Data Triggers. A useful by-product of defining indexes is that the data is automatically ordered within each index....................................................................... you could define this as an index................. For example................................................... we could search through the entire file until we came across it........... For example...... Fields A record is broken down into individual fields............................................. all the information in the customer file would be ordered by customer code within that index. A single field or a combination of fields can be used as an index... in much the same way as you would put index tabs on the folders in your filing cabinet.................................................................. Records A file is broken down into individual records................... then “SMITH001” is the key to this record.................... Files A database consists of individual files........................... there is a need to fully understand how data can and should be organised..................................................................................... if using the customer code field as an index into the customer file and the code “SMITH001” is used for customer “John Smith”........... A field holds a single value within a record....... there would be a record in the customer file for each customer............................. of all your customers........................ 223 Oracle Error Numbers........ In the traditional sense............ For example............. 217 Database Error Numbers.................. a quick method of looking into the file is needed... To decide which fields to use as indexes....... but this could take a long time................... city.................... For example............................ 221 C-ISAM Error Numbers... address and so on.................. 225 UNIX/Linux Error Numbers... Starting from the top down is the database............................... Further... Another term to be familiar with is key....................... As a result...................... A better way of doing this is to define an index into the file....... etc... the database can be considered as equivalent to the filing cabinets that hold all your data........................ suburb.....................................PRONTO-RAD 4GL Debugger............. A key is the set of values used in an index for a particular record. 9 ............... If a file is considered as being a table of information. ). PRONTO-Xi will only search in your current directory. a file. PROPRINTERS List of PRONTO-Xi printer names available for use. This environment variable allows Developers and Testers to run applications with their default data-grid settings. PRODICT Standard (default) dictionary to use. PRODISTDICT Distributor supplied dictionary to be used in addition to the standard and user dictionaries. PROCMPINC This environment variable can be used to define the directory in which the include file(s) reside when using procmp to compile a program. Your database is defined in a data dictionary. The name of the database instance containing the PRONTO-Xi data. which will contain a description of all your fields.Objects In PRONTO-Xi. Only these printers can be selected within the PRONTO-Xi print utility. If the full path name of the dictionary is not specified then the PROPATH environment variable will be used to find the location of the dictionary. If set to a non-null value. An object is the logical definition and actual data of a file. PRODATABASE RDBMS implementations only. separated by colons (:) or commas (. fields and indexes are tied together into what we term an object. The full network path to the PRONTO-Xi directory on the server machine. It has no effect on name views in the data-grid. If not set. PROPATH Runtime search path list for PRONTO-RAD programs and SQL queries. This environment must be set. NETPRONTO Windows implementations only. Environment Variables Used for 4GL Programming Certain environment variables can be set to alter or specify the way in which PRONTO-Xi performs certain functions. 10 . it indicates that the default view of a data-grid will not be shown with user modified column size positions. PRODEFDATAGRID Note: This environment variable is intended specifically for Software Developers and Testers. the default database instance for the machine will be used. This environment variable can be set to the full path name of a file to write log entries to if the runtime encounters user input when the application has locked records or is in a transaction. Tables that have application locks defined for them are not logged. If this environment variable is not set. and indexes. PROCMPCT This environment variable can be set to ‘Y’ in order to enable codified text translations when using procmp to compile a program. If this is not defined. PROLOGINTLOCKS This environment variable can be used to write log interactive locks to a file for analysis purposes only. its records. PROLOGLOSTLOCKS This environment variable can be used to write a log of lost locks caused by the SERIAL statement to a file for analysis purposes only. eliminating confusion caused by user changes to them. Data Dictionary PRONTO-Xi needs to know how your data is organised. then all defined printers are available. The environment variables recognised by PRONTO-Xi are: Environment Variable Description PRONTO PRONTO-Xi home directory. records/objects. All special PRONTO-Xi subdirectories are contained in this home directory. PROUSRDICT Custom dictionary to be used in addition to the standard dictionary. NO or FALSE Use non-XML format reports. ISO-8859-1 or GB2312. Note: The page header section is deemed to contain all lines printed from within the routine specified in the HEADER clause of the REPORT statement. The default font size for printing is 10pt instead of 6. Note: The page header section is deemed to contain all lines printed from within the routine specified in the HEADER clause of the REPORT statement. PROXMLHEADERBG Sets the default background colour for the report page header when generating an XML/XSL report (when no customised style sheet or CSS is being used). SPOOL or SPOOL-ONLY Do not pass XML through the viewer when report is generated. PROXMLHEADERFG Sets the default foreground colour for the report page header when generating an XML/XSL report (when no customised style sheet or CSS is being used). Note: This setting is also used when exporting data grid columns to Excel using the ‘Export Columns’ tool on the PRONTO-Xi toolbar. The character set specified must be supported by the XML transformers. PROXMLDISPLAYSIZE Sets the default display font size when generating an XML report (when no customised style sheet or CSS is being used). For example. PROXMLPRINTSIZE Sets the default print font size when generating an XML report (when no customised style sheet or CSS is being used). PROXMLREPORTS Specifies the report format and how the report is to be viewed.This environment variable can be set to the full path name of a file for which to write log entries. PROXMLENCODING This environment variable sets the XML character set code used when generating an XML report. PROXMLDETAILFG Sets the default foreground colour for the report detail/body when generating an XML/XSL report (when no customised style sheet or CSS is being used). This environment variable adds the “encoding=” tag to the headers of the XML and XSL report files.7pt for reports declared as 80 columns or less. Any 8-bit characters in the data are stored in the XML files without change. If this environment variable is not set. The contents of the log record are the following comma separated fields: 1 Name of user 2 Path of operations table containing SERIAL statement 3 Name of procedure containing SERIAL statement plus up to 3 calling procedures 4 Module code 5 Function code 6 Path of operations table containing objects that lost locks 7-10 The names of up to 4 objects that have lost locks PROXMLDETAILBG Sets the default background colour for the report detail/body when generating an XML/XSL report (when no customised style sheet or CSS is being used). then non-XML format reports are generated. VIEW or Pass XML through the viewer at generation and 11 . ’). The value ‘Y’ or ‘y’ turns on single keystroke menu selection. If this is not defined PRONTO-Xi will spool all reports into your current directory (usually the data directory). Any other non-null value will currently be interpreted as required reports in XML format. If this is defined it overrides any default terminal type defined for your terminal within PRONTO-Xi. This only applies to UNIX systems. TERM Terminal type name as defined in the terminfo database (for example.VIEW-ONLY remove spooled XML report when finished. PROTERM This can be used to specify a PRONTO-Xi specific terminal type. PROWEEKDAYS Comma-separated list of 7 day names to override the default English names. This is intended for use in countries whose years are not based on the Gregorian calendar. 12 . Note: This only applies to UNIX/Linux based machines. BMS The parent directory where the standard PRONTO-Xi applications are installed. PROCPUSTATS CPU performance statistics for all PRONTO-RAD programs and PRONTO-SQL Queries are recorded in the file specified by this environment variable. Any PRONTO-Xi program waiting for input for greater than the time specified will be aborted. CUS The directory where customer specific applications are installed. TMPDIR The directory in which to place all temporary files generated. PROTIMEOUT Specifies an input timeout in minutes. If this is set it overrides the TERM environment variable when a PRONTO-Xi program is executed. PATH Search path list for external (non-PRONTO-Xi) commands executed. month and year ordering) to use. EDIT Your favourite text editor. The TERM environment variable will be used for non-PRONTO-Xi programs. PRODATEFMT Sets the required date format (day. which will be spooled and viewed. PROSINGLEKEY This environment variable allows the system wide setting for single keystroke menu/mode selection to be overridden. If this is not defined PRONTO-Xi will default to what it considers to be the best text editor on your system. PRODECPT Sets the default decimal point character to use (either ‘. The value ‘N’ or ‘n’ turns it off. SHELL The default shell to run when a shell is invoked. REPORTDIR The directory in which to place all report (spool) files generated. If this is not defined PRONTO-Xi will default to the standard temporary files directory on your system. 1 DD/MM/YY Ordering 2 MM/DD/YY Ordering 3 YY/MM/DD Ordering (not currently supported) PROYEAROFFSET Sets the number of years to offset from the system date. VT100). ‘$’) to use. PROMONTHS Comma-separated list of 12 month names to override the default English names.’ or ‘. Note: This only applies to UNIX/Linux based machines. PROCURRENCY Sets the default currency symbol (for example. Path lists as required by PROPATH and PATH are a set of one or more directory names (usually specified with their full path). The format of an entry is: NAME=VALUE or set NAME=VALUE A line beginning with hash (#) in the ‘environs’ file is treated as a comment line. The file /etc/pronto_dirs is used to list the valid path(s) of the PRONTO-Xi directories on the machine. that is. 3. Local PRONTO-Xi environment settings. the separator for a path list is a semi-colon (. The runtime validates the PRONTO-Xi environment against the contents of this file to ensure that only valid PRONTO-Xi directories can be used. Declarations This section defines the storage and procedural structure of the PRONTO-RAD 4GL programming language. Global environment settings in the ‘PRONTO/lib/environs’ file. each separated by a colon (:). Global Affects all workstations accessing PRONTO-Xi.) since colons are used to specify a device. UNIX/Linux Environments UNIX (Bourne shell) PROPATH=/home/pronto/bms:/home/pronto/bin. any local workstation environment settings of the same name. PRONTO-Xi environment variables can be maintained via the Environment menu command (accessed via the menu bar by selecting File \ Settings). take precedence over. the relevant environment variable specifications for that machine will be written to the local PRONTO-Xi environment area. Environment Description Local Workstation Only affects the current workstation. For example: # Set up global PRONTO-Xi environments INVOICES=printer1 CHEQUES=printer2 These environment settings do not override. On a Windows system the environment setting precedence is as follows: 1. Any environments set (via Windows) when a PRONTO-Xi program is launched will take precedence over the local PRONTO-Xi environments. 2. These environment variables are maintained in the ‘environs’ file located in the ‘PRONTO/lib’ directory on the server machine. These files are located in the $PRONTO\lib directory. the relevant environment variable specifications will be written to the files sh_environs and csh_environs. On Microsoft Windows systems. Windows Environments During installation of PRONTO-RAD on a Windows system. Directories are searched in the order that they appear in the list. The current directory is not searched unless it is specified in the list or a colon appears first in the list. Windows environments set prior to launching a program. 13 . export PROPATH UNIX (C shell) setenv PROPATH /home/pronto/bms:/home/pronto/bin During installation of PRONTO-RAD on a UNIX system. This file is created and maintained automatically on installation and upgrade of the runtime. the DATE-TIME clause could be written as:  DATE-TIME  DATETIME  DATE_TIME PRONTO-RAD supports the following declarations: API MODE RETURNING FIELD OBJECT SCREEN LOCAL PARAMETER MENU PROCEDURE API Declaration This is a special type of procedure that defines an API function. TYPE Type of field. These functions can be called from external applications (for example. then a default TYPE will be allocated. Syntax See Also API api-function-name [procedure-clauses] procedural-statements [END-API] PROCEDURE.Where a clause for a function or statement contains a hyphen (‘-‘). If only PIC is specified. 14 . . TYPE and PIC can be used together. a Web Application Server) using the Pronto Integration Engine (PIE). The name of the field must be a valid name and must not be defined in the dictionary being used. DO FIELD Declaration This defines a data field that does not belong in any of the objects being referenced. Refer to the PROCEDURE Declaration for clauses and usage. Several fields can be defined within the one FIELD statement. the clause can also be written as a single word or by using an underscore (‘_’). SCREEN. Syntax Clauses FIELD field-name [TYPE [IS] type] [PIC [IS] picture] [OCCURS occurrence [TIMES]] [LIKE field-name-2] [UPPERCASE|LOWERCASE] [JUSTIFY] [USE-NAME-IN-DB] [DB-COLUMN-NAME [IS] alpha-literal] [DRILL-BACK [IS] alpha-literal] field-name . If only TYPE is specified. This statement is nonprocedural. . See the ‘Data Types’ section for more detail. Fields defined using the FIELD statement are global to the program. but neither can be used in conjunction with the LIKE clause. MENU. For example. they cannot be referenced until after they are defined. It can occur anywhere in the program without affecting the program’s logic flow. then a default PIC will be allocated. however. Notes The format of NUMERIC. JUSTIFY The ACCEPT statement will right justify any characters entered. OLE-INTERFACE Used to store an OLE interface ID. Times from 00:00:00 to 23:59:59 can be stored. FLOATING Floating-point numeric format. Data Types NUMERIC or DECIMAL Default numeric format. Dates from January 1. Trailing blanks (spaces) are ignored by certain functions (for example. 1900 through to 2079 can be stored. This data type may only be specified for fields defined within a 4GL program. The picture is in the format of a standard picture string (without numeric editing characters). FLOATING and ZONED types when stored in a RDBMS will 15 . The parameter being passed must be a global field and have a ‘%’ either side of the parameter. DATE-TIME Date and time format (used for time stamps). neither the TYPE or PIC clauses can be specified. For example: drillback is “testprog %field-name%” Local fields can not be specified as the parameter (between the %). If this clause is used. ALPHA Alphanumeric character string of a fixed size. It will be stored as either single or double precision depending upon the PICTURE of the field. DRILL-BACK Defines the program to launch to perform a data drill back for this field when it is included in an XML report.PICTURE or PIC Picture of the field. UPPERCASE The ACCEPT statement will map any lowercase characters entered to uppercase. This is stored as a fixed precision computational/binary value. The full size of the field defined (including trailing spaces) is used by most functions. See Notes below. STRING Alphanumeric character string. BOOLEAN Numeric format is used to store TRUE/FALSE values. DATE Date format. type and occurrence will be the same as that of field-name-2. USE-NAME-IN-DB The field’s name will be used as its column name if this field is contained in a table stored in an RDBMS. ZONED Zoned decimal numeric format (obsolete). COLOUR or COLOR Numeric format used to store a colour. LIKE The field’s picture. LOWERCASE The ACCEPT statement will map any uppercase characters entered to lowercase. DB-COLUMN-NAME Specifies the column name for this field if it is used in an RDBMS table. See Notes below. CONCAT()) when fields of type STRING are used. TIME Time format (within a single day). This data type is not valid for dictionary based fields. (Minus) or S Indicates the position of the sign character when a value is negative. as the value will be lost (due to overflowing) if the field is written to an EXTERNAL file. Fields of type DATE-TIME which are directly associated with an ACCEPT or DISPLAY statement are interpreted as being GMT based (not local time based). This character. . When this character is repeated multiple times. COLOUR can be used for defining colour fields. It is not recommended to use these as 16 . The bracket characters must surround all other picture string characters. Fields of type TIME should not be used to store these values.80 COLOUR IS ws-back ON ws-fore Data Definition Picture Strings These picture string characters are used to specify the format of a field being defined. GMT and SYS-TIME functions. number of integer/decimal places and whether the field allows negative amounts. otherwise it represents an integer digit. When this character is repeated multiple times. Character Description 9 Represents a single numeric digit. This is for defining alphanumeric fields only and should not be combined with any of the above characters. must appear at the start of the picture string.be the native RDBMS numeric format. This DATE-TIME data type is intended to store time stamp values returned by the DATE-TIME. X Represents a single alphanumeric character. When this character appears after a decimal point. DR or CR Displays “DR” or “CR” if the value is negative. These values should be displayed using the DATE-FROM-DATE-TIME and TIME-FROM-DATE-TIME functions. when used. the currency sign will “float” over leading zeros to be positioned before the first non-zero digit. Z Similar to ‘9’ except leading zeros are suppressed. the minus sign will “float” over leading zeros to be positioned before the first non-zero digit. The following is a list of the valid picture string characters and their use. DATETIME values do not have any special formatting characteristics and will be displayed as a number only.1 TO @22. They indicate the size of the field. This may happen if the file is being exported or imported. For example: FIELD ws-back TYPE COLOUR ws-fore TYPE COLOUR PROCEDURE main SET ws-back = BLUE SET ws-fore = RED DO deb-maint END-PROCEDURE SCREEN deb-maint PRIMARY deb-master WINDOW @1. () Displays a negative value in brackets.’ except all decimal places and the decimal point are shown as blank when the value is zero. it represents a decimal digit. T Similar to ‘. (Dot) or V Specifies the location of the decimal point. % Displays a percentage sign $ Displays the currency sign. . This defines fields that are local in scope to the routine. The local field will remain totally independent of any global field with the same name. Certain picture characters are often required to be repeated. Syntax MENU menu-name [WINDOW [@row.. AFTER and DETAIL). popup or the traditional button format) is controlled by the TREE-MENU and NO-HIDE clauses. For example.these symbols are only meaningful in English speaking countries. The menu will loop until it is backed out of or until an EXIT statement is encountered. The presentation of the menu (for example. If this is the first routine defined for the program (or its name is main) then this will be executed initially. All explicit references to the field within the routine will apply only to the local field. A local field can only be referenced within the routine that defined it.. The data storage for a local field is allocated upon each invocation of the routine (and de-allocated upon its exit).col] [RELATIVE TO @row.. MENU and PROCEDURE declarations. The repetition of a picture character can be expressed as follows: pic-char(amount) For example: X(10) The PIC clause is also used as ‘Data Edit’ strings on the DISPLAY and ACCEPT statements. LOCAL Declaration The LOCAL declaration is a clause to the SCREEN. The routine should contain menu options (using the OPTION statement) and procedural commands to perform if that option is selected. This statement will automatically end any previous SCREEN.] [PARAMETERS [ARE] field-name field-definition . screen or menu in which it is defined.] [RETURNING] field-name field-definition . allowing for true recursive routines. The procedural code itself can be broken up into three command groups (BEFORE.. No error/warning will be issued if the name of a local field matches the name of a globally defined field.col]] [WINDOW-POSITION [IS] numeric-value] [LOCAL [FIELD] field-name field-definition . API or MENU declaration. FIELD Declaration.. menu or procedure declaration and before any procedural code.] [BUTTON-WIDTH [IS] numeric-literal] [STOP-EXIT-ALL-KEY] [TITLE [IS] alpha-expression] [TREE-MENU] [NO-HIDE] [COLOUR [IS] colour [ON colour]] [EXPORT|USER-TRIGGER [CAN-OVERRIDE|NO-OVERRIDE]] 17 .col TO @row. For further information refer to the PICTURE clause details in the ‘DISPLAY Statement’ section.. It must appear immediately after the screen. MENU Declaration Defines a menu.. PROCEDURE. This function has exactly the same syntax as the FIELD declaration except that it is local in scope to the procedure. to specify a picture of ten alphanumeric characters enter: XXXXXXXXXX Another way of specifying the repetition of a picture character is by using repetition factors. Syntax See Also LOCAL [FIELD] field-name field-definition . tree format.. 2 means top/centre and so on. When the menu returns. If RELATIVE TO is specified. This code is performed for each selection from the menu. For example: WINDOW-POSITION IS 8 Note: Data grid columns do not currently support decimal addressing. If no co-ordinates for the window are specified then the window will occupy the entire screen. UNIX/Linux implementations require Thin Client release 6. LOCAL The LOCAL declaration defines fields that are local in scope to this routine. DETAIL This contains the iterative code for the menu. PARAMETERS Allows the definition of parameters that are passed to the routine. The row/column co-ordinate for each field in the data grid must use whole numbers.0 or later. The following values are currently supported: -1 Run this window in full screen mode. headings). This is performed once at the start of the menu. AFTER Specifies the AFTER command group. The row and column values can be arithmetic expressions. For further details refer to the ‘LOCAL Declaration’ section. 18 .[BEFORE procedural-statements] [DETAIL procedural-statements] [AFTER procedural-statements] [END-MENU] Clauses WINDOW The menu is defined as being a window over the current screen. This is performed once when exiting the menu.5v0. Used to specify a numeric value indicating the size or initial position of the window. This should contain any finalisation code for the menu. 1 to 9 The initial position of the window within the container window. BEFORE Specifies the BEFORE command group. the position of the window will be relative to these co-ordinates. WINDOW-POSITION This clause only has affect if the WINDOW clause is also specified. This should contain any set up code for the menu (for example. This command group should contain OPTION statements for every menu entry. For further details refer to the ‘PARAMETER Declaration’ section. The numbers are based on the following grid: 1 2 3 4 5 6 7 8 9 Where 1 means top/left. the window will disappear automatically. For example: MENU test-menu 19 . the 4GL will automatically back out all programs being run by the user. STOP-EXIT-ALL-KEY When F8 (Exit All) is pressed. COLOUR or COLOR The COLOUR clause is valid for a SCREEN/MENU/PROCEDURE to specify the default window colours. Note: A routine with this clause specified will not stop the EXIT-ALL operation if the EXIT-ALL key was pressed whilst in the routine. The automatic backout will be cancelled when a routine with this clause specified is encountered. When ‘0’ or no colour is specified the user’s default colours will be used. a 10 second limit is placed on the EXIT-ALL operation by PRONTO-Xi. All screen output is stopped while in this mode. it is assumed to be the background colour. as this timeout may not be available on all systems (for example. MENU and PROCEDURE declarations to also stop the EXIT-ALL operation. to try and allow the programs to back out gracefully. When running on a version of PRONTO-Xi that supports buttons. The STOP-EXIT-ALL-KEY clause was added to the SCREEN. A positive value indicates that all buttons must be at least this size (in characters). This should not be relied upon. Any code that loops to stop a user from being able to exit by pressing <Esc> (other than by using the BACK-TO-DETAIL statement) can cause the application to hang if the EXIT-ALL key is pressed. as the intention of this statement is to stop users from being able to exit the screen by pressing <Esc>. As a fail-safe. A negative value indicates that all buttons will be the size of their prompt. It accomplishes this by flagging that all requests for keyboard input will be treated as though the <Esc> key had been pressed. all buttons for the MENU will be the same size by default. but the text will be centred within the button (as per a MODE).RETURNING Allows the definition of parameters that are returned to the calling routine. For further details refer to the ‘RETURNING Declaration’ section. If only a single colour is specified. It only has effect if the EXIT-ALL key is pressed in a child routine. Any routines that contain this type of code should either be rewritten or specify the STOP-EXIT-ALLKEY clause to avoid this problem. The size being that of the largest prompt for any of the OPTIONs in the menu (regardless of its row/column position). it will automatically be cancelled. The EXIT-ALL operation will be cancelled if the program executes a BACK-TO-DETAIL statement. DOS). If the EXIT-ALL is still in effect after 10 seconds. For example: COLOUR IS RED ON 0 This clause is only valid if the WINDOW clause is also specified (with the exception of the main window). A value of zero indicates that the button sizes will be calculated (as per normal). BUTTON-WIDTH This clause allows the width of the buttons used when displaying the prompts for the OPTIONs to be controlled (in versions that support button drawing). NO-HIDE If a valid tree menu is active (without child screens invoked). Menus are defined within a program in the traditional way. OPTION. EXPORT Indicates that the routine is an entry point to an operations table when used as a component library. DO. A menu invoked while there are no visible windows (excluding the tree view) will be shown within the main tree view menu by default. USER-TRIGGER Notes This clause is similar to the EXPORT clause described above. API. then the menu will form part of this tree menu. For further information refer to the ‘Row/Object Parameters’ section. For example. the traditional menu is used. The positioning of the popup menu after the user selects an option is not guaranteed. then a NO-HIDE clause on the routine that defined the window will also override the TREE-MENU clause. Any popup menu should exit once the option has been performed. the CONFIRMED section of the CONFIRM should finish with an unconditional EXIT. This will set the title on the title bar of the window. When running on a character based device. If the MENU contains the NO-HIDE clause then the TREEMENU clause has no effect. For further details refer to the ‘EXPORT Clause’ section. The position of the popup will be based on the top/left coordinates of the last input field or menu option used. A popup menu is restricted to a maximum of 25 menu items.BUTTON-WIDTH IS 35 TITLE The TITLE clause is available for any MENU/SCREEN/PROCEDURE with a window. A tree view menu system is provided for navigating through the application’s menu instead of the traditional button based menus. Any menu invoked while there are visible windows (excluding the tree view) will be shown as a popup menu by default. If the MENU routine does not define its own window. Multiple tree menus are supported. In this circumstance the procedure will be the first performed for the program regardless of its location in the program. See Also PROCEDURE. Otherwise a new tree menu will be created. The NO-HIDE option on the MENU will cause the menu to be displayed in the traditional way rather than via a popup (or tree view). but additionally permits the routine to be called as a component library trigger by the Screen Customiser. A menu shown as a tree view (or popup) ignores any DISPLAY statements that may be present. There is a special case where the name of the menu is called ‘main’. Parameters for a routine can be defined as a completed row/record for an object. It is processed once only upon entry to the routine. SCREEN. EXIT 20 . TREE-MENU The TREE-MENU clause on a MENU can be used to indicate to the runtime that this menu should be displayed as a tree style menu instead of a popup menu. It can occur anywhere in the program without affecting the program’s logic flow. their standard definitions can be changed using this statement. ENTRY-ONCE Put screen into [Entry] mode for all ACCEPTed fields. CORRECT. once the screen has been processed. This mode implies CURRENCY. Syntax Clauses MODE mode-name [PROMPT [IS] alpha-expression] [HELP [IS] alpha-literal] [SECURITY [IS] numeric-literal] [ENTRY | CORRECT | REMOVE | DUPLICATE | ENTRY-ONCE | FIND | NEXT-SCR | PREV-SCR] [PROCESS] [CURRENCY] [LOCK] [PERFORM routine-name] [WHEN condition] [COLOUR [IS] colour] [ICON [IS] icon-name] [ALWAYS-SHOW] PROMPT Defines the prompt displayed in the mode prompt line. rather than updating the current record. DUPLICATE This mode is used to duplicate/copy the current record. if any. [Entry] mode will automatically position the user for entering another record. A mode defined by a MODE statement is global to the entire program. CURRENCY Record currency is required on the screen’s PRIMARY object. CORRECT Put screen into [Correct] mode for all ACCEPTed fields. ENTRY Put screen into [Entry] mode for all ACCEPTed fields.MODE Declaration This statement is used to define screen modes. LOCK This causes the mode to re-read and lock the current primary object record when selected. The record will remain locked until the next operation is performed on the object. Single iteration only. It acts exactly as [Correct] mode during screen input. it cannot be referenced until after it is defined. This applies to the user’s global security level number. control is returned to the mode menu. 21 . that is. REMOVE. If none is specified then mode-name is used as the prompt. for this mode to be valid. However. This statement is non-procedural. however the values will be inserted into a new record. The SEARCH. PROCESS If a PRIMARY object is defined for the screen then process the file with the specified mode: ENTRY. However. This has no real effect unless the PROCESS clause is also used. ENTRY. REMOVE Put screen into [Remove] mode. Note: Application security no longer uses the global security. ENTRY-ONCE and DUPLICATE modes are already defined by the language. CORRECT or REMOVE. HELP Define a help line to be displayed for the mode SECURITY Specifies the minimum security level required to access this screen mode. MENU or PROCEDURE whenever this mode is selected. by default the mode will be omitted. The following predefined icon types are available: FOLDER-ICON ADMIN-FOLDER-ICON REPORT-FOLDER-ICON ADMIN-ICON REPORT-ICON SCREEN-ICON TRANSACTION-ICON PERIOD-END-ICON QUESTION-ICON BLANK-ICON FAVOURITES-FOLDER-ICON LOCKED-FOLDER-ICON BLUE-FOLDER-ICON RED-FOLDER-ICON GREEN-FOLDER-ICON ENQUIRY-FOLDER-ICON For example: OPTION "TESTING" @10. If the WHEN clause is invalid when the modes for a screen are initially shown. ALWAYS-SHOW This clause only has effect if a WHEN clause is present for a Mode. COLOUR or COLOR For example: COLOUR IS RED ON BLACK COLOUR IS BLUE When ‘0’ or no colour is specified the user’s default colours will be used. The colours can be specified as an expression (and hence can be varied at runtime). Mode icons are visible upon right-mouse click. A mode with the ALWAYS-SHOW clause will always be added to the screen regardless of the initial state of the WHEN condition. The WHEN condition is only evaluated when the modes are initially displayed for the screen (after the BEFORE section is processed) or when the screen is redisplayed due to the issue of the REFRESH statement. A field type of COLOUR (for example. Either the foreground or the foreground and background colours can be specified. Fields storing colours must be at least PIC 9(5).10 22 .PERFORM Perform the specified SCREEN. WHEN The mode will only be valid for a screen if the condition specified for the WHEN clause is true. ICON is The icon used in screen and tree menu based buttons can be specified by using the ICON clause on both the OPTION statement and MODE declaration. TYPE IS COLOUR) can be used. For example: COLOUR IS RED ON 0 The standard PRONTO-Xi/PROCLIENT colours are supported (as per File -> Settings -> Color). Note: The ALWAYS-SHOW keyword is interchangeable with the NO-HIDE keyword. Any change in the result of the WHEN condition after this point will not affect the modes available unless the screen is invoked again or is REFRESHed. . This statement is non-procedural. however. however. Notes Selection character: The character required to select the MODE using the keyboard can be specified by prefixing the character with an ampersand (&) in the prompt. does not allow expressions. .. For example. It can occur anywhere in the program without affecting the program’s logic flow. a double ampersand (&&) must be specified in the prompt. . For example: SET option-title = "TESTING" SET icon-number = SCREEN-ICON . they cannot be referenced until after they are defined. . END-RECORD] [KEY [IS] field-name [DESCENDING|DESC] . OPTION option-title @10. If the prompt does not specify a selection character explicitly.. [NO-JOINS] [NO-ROWID] object-name . LIKE This indicates that object-name is an alias of object-name-1. The MODE declaration. . . .. To print a single ampersand. Objects declared using the OBJECT statement are global to the entire program.10 ICON IS icon-number Note: The width of the mode button can be extended up to two characters depending on the length of the mode prompt. Syntax Clauses OBJECT object-name [LIKE object-name-1] [TYPE [IS] file-type] [SEPARATOR [IS] alpha-literal] [FILE [IS] alpha-literal] [RECORD [IS] field-name [TYPE [IS] type] [PIC [IS] picture] OCCURS occurrence [TIMES] [LIKE field-name-2] field-name . the first printable character in the prompt will be used. DO OBJECT Declaration This statement defines new objects to be used by the program that are not defined in the dictionaries used.ICON IS SCREEN-ICON The OPTION statement allows the icon type to be specified by a numeric expression (or field name) to allow for variable options. “E&xit” specifies x as the selection character. See Also SCREEN. [UNIQUE] [DB-INDEX-ONLY] [COMPRESS]] . object-name will contain all the definitions of object-name-1 23 . NO-JOINS The NO-JOINS statement specifies that no fields defined for this object will be joined to other fields of the same name within the program. Where the C-ISAM files has multiple keys. SEPARATOR Defines the separator character used for EXTERNAL type files. KEY Defines the fields that make up a key when the file type is ‘ISAM’. the field can optionally be specified without the object prefix. With some exceptions. if the object being defined is called ‘deb’ and it contains the field ‘accountcode’. These indexes can only be defined after all normal indexes. Descending key fields retrieve their highest value first. The field ‘deb. If the object is defined with an OBJECT statement. If the definition of the required field is defined in the dictionary or in a previous FIELD statement. all references to fields from the object defined must be prefixed with the object’s name. In circumstances where only fields from the object can be specified (for example. The clause specifies that the index is only to be created on relational database versions.accountcode’. A separate file can be created if the programmer uses the OPEN statement with the FILE IS clause to specify a separate disk file. then only the field name should be specified. Note: there is still only one file. TYPE Specifies the type of file the object refers to. By using the like function the programmer can maintain two independent indexes into the file. DB-INDEX-ONLY This clause must occur after the field list for the key being defined. RECORD Defines the record layout for the object. This may reduce the storage requirements for the index on some systems. Be aware of this when positioning the file with the POSITION statement. although it is likely to increase the processing overhead of index maintenance. The separator defined must be an alphanumeric literal string of one character in length. The field definitions are the same as that used in the FIELD statement. ON INDEX). descending key fields can be specified by placing the DESCENDING (or DESC) clause directly after the field’s name in the KEY IS clause. COMPRESS Specifies that full key compression be used by this index (if supported). See File Types below.accountcode’ is considered a different field to ‘accountcode’. specify each key with a separate KEY clause.* 24 . DESCENDING Descending fields may be defined in an index for an object. For example. you must refer to the field as ‘deb. FILE Defines the path-name of the physical file for the object. If an open truncate is executed on the like object it will delete all the records in the original file. The values of prefixed fields can be copied between NOJOINS objects and also imported/exported to their nonprefixed counterparts with the following SET statements: SET * = object-name.but will be considered as a separate object whenever referenced. Each Field has the length of the field itself. A file name is required to be specified for memory files. The text file type is a normal UNIX type record. 25 .* NO-ROWID This clause is primarily intended for RDBMS tables. a multi-table view). insert. File Types EXTERNAL Variable length record. Notes External file. Memory files are intended for small to medium size temporary files only. update or delete records. Avoid using these files if it is expected that a large number of records will be inserted (for example. INDEXED or Index-sequential file with one or more indices defined. The fields for the object will be specified individually to the RDBMS and never by a wildcard (*). A CR/LF terminates each record. Text fields are surrounded by quotes and the record terminates with a CR/LF combination DB-SEQUENTIAL This is the equivalent of a sequential file for use in relational database systems. This is one long ASCII data stream. They can be used with other file I/O statements. TEXT Variable length record (trailing spaces from the last field are removed). No separators between fields. These files have a read-only access and are intended for transferring data to a relational database product.dat’ file in a C-ISAM system in a sequential manner only. It specifies that rows from the table cannot be retrieved by ROWID (for example. fixed length text and prn file types will all create records with a CR/LF combination at the end of each record ready for use on a PC.SET object-name. This is intended for temporary files only. They also cannot be used as a PRIMARY object within a SCREEN. Only the program that created the memory file can access the records of the memory file Memory files can be defined and accessed in exactly the same way as normal indexed/C-ISAM files. NO-ROWID objects cannot lock. as the records will be lost when the program exits. MEMORY The indices and a cache of records are stored in memory. however. FIXED-LENGTH-TEXT This is the same as TEXT except the trailing spaces at the end of the last field in each record are not removed and the file has a CR/LF combination terminating each record. Fields are separated by the separator character. The file is stored as a non-indexed table C-ISAM-DAT This definition allows access of the ‘. The operations in a memory file cannot currently be rolled back. for example GET.* = * SET object1-name. a file of that name will not be created. This allows only a portion of the actual fields that make up the table to be selected. ISAM PRN / CSV Text file with comma separators (separator clause is ignored if present). SELECT and EXTRACT. The file name is required to allow LIKE objects to refer to the same memory file within the program.* = object2-name. SEQUENTIAL This is the same as TEXT except there are no separators between records. MENU and PROCEDURE declarations. MAIN) routine executed within the program.. however. INSERT. then the fields will contain the parameter values passed to the program (for example. UPDATE. menu or API. Each ACCEPT statement will be processed in turn. This statement will automatically end any previous SCREEN. This identifies the list of fields that will contain the parameter values passed by the DO statement which calls the routine. A procedure can take input from the screen through ACCEPT statement(s) if required. and the user has the opportunity to arrow back to a previous ACCEPT. No error/warning will be issued if the name of a local field matches the name of a globally defined field. GET. via the SPL/CALL statement).. Syntax See Also PARAMETER[S] [IS|ARE] field-name field-definition . POSITION. menu or procedure declaration and before any procedural code. CAN-OVERRIDE and NO-OVERRIDE clauses can be used on screens. API or MENU declaration. The data storage for a local field is allocated upon each invocation of the routine (and de-allocated upon its exit). allowing for true recursive routines. A procedure is called in the same way as a screen.col]] [WINDOW-POSITION [IS] numeric-value] [COLOUR [IS] colour [ON colour]] [LOCAL field-name field-definition . USER-TRIGGER. All explicit references to the field within the routine will apply only to the local field. This function has the same syntax as the FIELD declaration except that it is local in scope to the procedure. SERIAL.. PROCEDURE.] [STOP-EXIT-ALL-KEY] [TITLE expression] [EXPORT|USER-TRIGGER [CAN-OVERRIDE|NO-OVERRIDE]] .. CLOSE.. If this is the initial (for example. FIELD Declaration PROCEDURE Declaration This defines a standard procedure containing a list of PRONTO 4GL statements which are executed sequentially in top-down order. The local field will remain totally independent of any global field with the same name. If this is the first procedure defined for the program (or its name is main) then this will be executed initially.] [RETURNING field-name field-definition .[AUTO-TRANSACTION] procedural-statements [END-PROCEDURE] 26 . they return once the end of the procedure is encountered. menus. It must appear immediately after the screen.. See Also OPEN. Generally. procedures or API declarations. procedures do not loop automatically. A local field can only be referenced within the routine that defined it. screen or menu in which it is defined... Syntax PROCEDURE procedure-name [WINDOW [@row.col TO @row. for re-iterative screen input.. a screen declaration should be used. DELETE.. Unlike menus and screens.col] [RELATIVE TO @row. EXTRACT.over 500). UNLOCK PARAMETER Declaration The PARAMETER declaration is a clause to the SCREEN.] [PARAMETERS [ARE] field-name field-definition . Note: The EXPORT. The STOP-EXIT-ALL-KEY clause was added to the SCREEN.0 or later. For example: WINDOW-POSITION IS 8 Note: Data grid columns do not currently support decimal addressing. as the intention of this statement is to stop users from being able to exit the screen by pressing <Esc>. UNIX/Linux implementations required Thin Client release 6. Used to specify a numeric value indicating the size or initial position of the window. If no co-ordinates for the window are specified then the window will occupy the entire screen. The row/column co-ordinate for each field in the data grid must use whole numbers. STOP-EXIT-ALL-KEY When F8 (Exit All) is pressed. The EXIT-ALL operation will be cancelled if the program executes a BACK-TO-DETAIL statement. The row and column values can be arithmetic expressions. For further details refer to the ‘PARAMETER Declaration’ section. 1 to 9 The initial position of the window within the container window. MENU and PROCEDURE declarations to also stop the EXIT-ALL operation. the window will disappear automatically. WINDOW-POSITION This clause only has affect if the WINDOW clause is also specified. The following values are currently supported: -1 Run this window in full screen mode. RETURNING This clause allows the definition of values that are returned to the calling routine.5v0. For further details refer to the ‘RETURNING Declaration’ section. LOCAL The LOCAL declaration defines fields that are local in scope to this routine. It accomplishes this by flagging that all requests for keyboard input will be treated as though <Esc> had been pressed. the window will be displayed relative to these co-ordinates. All screen output is stopped while in this mode. When the procedure returns. to try and allow the programs to back out gracefully. For further details refer to the ‘LOCAL Declaration’ section. the 4GL will automatically back out all programs being run by the user. If RELATIVE TO is specified. The automatic backout will be cancelled when a routine with this clause specified is 27 . 2 means top/centre and so on. PARAMETERS Allows the definition of parameters that are passed to the routine.Clauses WINDOW The procedure is defined as being a window over the current screen. The numbers are based on the following grid: 1 2 3 4 5 6 7 8 9 Where 1 means top/left. it is assumed to be the background colour. If only a single colour is specified. AUTO-TRANSACTION When the procedure is invoked and there is no transaction in progress. then the transaction is committed. If the procedure exits via any other method (for example. AUTO-TRANSACTION allows independent components to be called without affecting the transaction control of the calling 28 . This will set the title on the title bar of the window. If the EXIT-ALL is still in effect after 10 seconds. a 10 second limit is placed on the EXIT-ALL operation by PRONTO-Xi. Any routines that contain this type of code should either be rewritten or specify the STOP-EXIT-ALLKEY clause to avoid this problem. The REVIEW COLOUR clause can be used in a review screen to specify the background colour for the review area. If the procedure runs to completion or exits via an EXIT statement with a zero (0) exit status. If only a single colour is specified. Note: A routine with this clause specified will not stop the EXIT-ALL operation if the EXIT-ALL key was pressed whilst in the routine.encountered. via an EXIT statement with a non-zero status) the transaction will be rolled back. depending upon the exit status of the procedure. This clause is only valid if the WINDOW clause is also specified (with the exception of the main window). as this timeout may not be available on all systems (for example. The TITLE clause is available for any MENU/SCREEN/PROCEDURE with a window. EXPORT Indicates that the routine is an entry point to an operations table when used as a component library. If a transaction is already in progress when the procedure is invoked. a transaction will be automatically started. it is assumed to be the background colour. must have the NO-HIDE clause specified. It only has effect if the EXIT-ALL key is pressed in a child routine. the transaction will be either committed or rolled back. As a fail-safe. but is required to be shown. USER-TRIGGER This clause is similar to the EXPORT clause described above.1 or higher. TITLE Valid for version 6. no automatic commit or rollback will be used on exit. This should not be relied upon. DOS). Any code that loops to stop a user from being able to exit by pressing <Esc> (other than by using the BACK-TO-DETAIL statement) can cause the application to hang if the EXIT-ALL key is pressed. but additionally permits the routine to be called as a component library trigger by the Screen Customiser. COLOUR or COLOR The COLOUR clause is valid for a SCREEN/MENU/PROCEDURE to specify the default window colours. It is processed once only upon entry to the routine. NO-HIDE Any window that does not contain input. it will automatically be cancelled. For further details refer to the ‘EXPORT Clause’ section. Upon exit of the procedure. This will not work for triggers. Can be referenced as a Screen Customiser Component Library Trigger // 3. Row/Object Parameters Parameters for a routine can be defined as a complete row/record for an object. Is only available for use in the 4GL program in which it is defined // 2. Can be called by 4GL Programs // 2. Rows may also be specified as return values. however. Can be called by 4GL Programs // 2. Can be overridden in a custom 4GL program (can-override is implied) PROCEDURE samplib1-open-the-paint-can EXPORT CAN-OVERRIDE // As Above PROCEDURE samplib1-ensure-paint-doesnt-spill EXPORT NO-OVERRIDE // Specifying the export and no-override clauses means that this routine: // 1. Cannot be overridden in a custom 4GL program USER-TRIGGER clause: PROCEDURE samplib1-wash-the-roof USER-TRIGGER // Specifying the user-trigger clause means that this routine: // 1.routines. then the calling routine needs to test the exit status of the component and act accordingly. If the component fails and wants the calling routine to fail and roll back its transaction. It only has an impact if there is no transaction active. This allows the entire row to be passed without the need to specify individual fields. See Also MENU. In this circumstance the procedure will be the first performed for the program regardless of its location in the program. DO. Cannot be overridden in a custom 4GL program No EXPORT or USER-TRIGGER clause: PROCEDURE samplib1-hand-me-the-paint // Not specifying either of these clauses means that this routine: // 1. Notes There is a special case where the name of the procedure is ‘main’. EXIT Example: EXPORT clause: PROCEDURE samplib1-paint-the-roof EXPORT //Specifying the export clause only means that this routine: // 1. as the calling routine is not aware that a trigger has been called. API. When only a subset of the record is needed it may be more efficient to pass individual fields. Can be called by 4GL Programs // 2. Is not available externally. Can be called by 4GL Programs // 2. Can be referenced as a Screen Customiser Component Library Trigger // 3. This mechanism is designed for passing row values to/from routines defined in component libraries. Cannot be referenced as a Screen Customiser Component Library Trigger // 3. Can be overridden in a custom 4GL program (can-override is implied) PROCEDURE samplib1-wash-the-roof USER-TRIGGER CAN-OVERRIDE // As Above PROCEDURE samplib1-stir-the-paint USER-TRIGGER NO-OVERRIDE // Specifying the user-trigger clause means that this routine: // 1. so cannot be overridden. SCREEN. Cannot be referenced as a Screen Customiser Component Library Trigger // 3. Note: The entire contents of the row/record is copied. in which case it will implement one automatically and either commit or roll it back when the component exits. 29 . This function has the same syntax as the FIELD declaration except that it is local in scope to the procedure.accountcode is ". Note: The GLOBAL clause is intended for passing rows to component libraries only and may be of no benefit if called from within the same component library or operations table. menu or procedure declaration and before any procedural code.accountcode Field values within a row can be copied using the same mechanism used for NO-JOINS objects. If you wish to return a field that is listed in the PARAMETER declaration of the routine then you must only list the name of the field omitting any definition clauses. The current row for the object is not affected. Multiple row parameters may be passed and/or returned. A routine can also receive a row into a globally defined object. The <row-name> row parameter is not an object definition. deb. 30 . as the field has already been defined.Method Passing a row parameter within the DO Statement Syntax PARAMETER IS object-name. Parameter rows defined using the LIKE clause are automatically defined as NO-JOINS. RETURNING Declaration The RETURNING declaration is a clause to the SCREEN.* PARAMETER row-name. A previously defined row can be returned (that is. This identifies the list of fields whose values will be passed back to the calling DO statement or to the calling program if this is the initial routine executed.* RETURNING deb.* PARAMETER object-name. screen or menu in which it is defined. File I/O operations can not be performed using <row-name>. It must appear immediately after the screen. Retrieving a row into a global object is similar to performing a RESTORE operation. as the same global data area is used for each call. without the need to prefix the object name unless the object itself is defined as NO-JOINS. Other parameter fields may also be passed/returned. allowing for true recursive routines. When a row is received into a global object parameter the fields within that object may be referenced as normal.* GLOBAL For example: PARAMETER IS deb-master. The data storage for a local field is allocated upon each invocation of the routine (and de-allocated upon its exit).* [RETURNING object-name. Routines that receive global object parameters should not be called recursively.*] Receive a row into a globally defined object For example: PARAMETER IS deb. The values of a globally defined object are also permitted to be returned.* LIKE deb-master.* [RETURNING row-name.* RETURNING deb-master. For further information refer to the ‘OBJECT Declaration’ section.*] Defining a routine with a row parameter For example: DO xyz PARAMETER IS deb-master.* GLOBAL For further information on the PARAMETER declaration refer to the ‘PARAMETER Declaration’ section. A local field can only be referenced within the routine that defined it. MENU and PROCEDURE declarations.* LIKE object-name. For example: MESSAGE "deb. This means that when referencing a field within a row this must be prefixed with its <row-name>. The physical file/table being processed by the object may be different to that of the object whose row was passed. a row defined as a parameter). col TO @row.No error/warning will be issued if the name of a local field matches the name of a globally defined field.. menu or procedure.] [STOP-EXIT-ALL-KEY] [POSITION-ON-OK|NO-OK-CANCEL] [STAY-IN-CORRECT] [FORM-ENTRY] [EXPORT|USER-TRIGGER [CAN-OVERRIDE|NO-OVERRIDE]] [BEFORE procedural-statements] [DETAIL procedural-statements] [AFTER procedural-statements] [END-SCREEN] WINDOW The screen is defined as being a window over the current screen.. Syntax Clauses RETURNING field-name field-definition .. The DETAIL section will loop until it is backed out of or until an EXIT statement is encountered. FIELD Declaration SCREEN Declaration Defines a routine that can be used for displaying and accepting data from the screen.col] [DATA-GRID OCCURS n] [REVIEW OCCURS n [BY n]] [REVIEW-FROM-START|REVIEW-FROM-CURRENT |REVIEW-FROM-END|REVIEW-BOTTOM-TO-TOP] [NO-REVIEW-ROW-SEPARATORS] [NO-REVIEW-COLUMN-SEPARATORS] [NO-REVIEW-SEPARATORS] [START-ON-CURRENT-RECORD] [LEAVE-PARENT-SCREEN] [WHEN condition] [LOCAL field-name field-definition .]] [NO-PROMPT-FOR-SEARCH] [PROMPT-FOR-SEARCH] [FIND-FOR-CURRENCY] [PROMPT @row. 31 ... Backing out of or EXITing the first procedure terminates the program.. PROCEDURE or MENU declaration. the window will disappear automatically. The local field will remain totally independent of any global field with the same name.. If this is the first procedure defined (or its name is main) then the program will start at this screen. All explicit references to the field within the routine will apply only to the local field. Syntax Clauses SCREEN screen-name [WINDOW [@row.. This screen can be called from another screen.] [RETURNING field-name field-definition . When the screen returns. This statement automatically ends any previous SCREEN.col]] [WINDOW-POSITION [IS] numeric-value] [TITLE expression] [PRIMARY object-name [ON INDEX index] [SAME | DIFFERENT [field-list]]] [SELECT select-clauses] [COLOUR [IS] colour [ON colour]] [REVIEW COLOUR [IS] colour [ON colour]] [ALLOWED [IS|ARE] mode [mode-name ..] [PARAMETERS [ARE] field-name field-definition ..col] [RELATIVE TO @row. The row/column co-ordinate for each field in the data grid must use whole numbers. Windows can be defined larger than 80X24 in size. The MAX-SCREEN-COLUMNS and MAX-SCREEN-ROWS functions can be used to determine the maximum available screen size for the current terminal.5v0. Otherwise. PRIMARY This defines the primary object that the screen will be accessing.If no co-ordinates for the window are specified then the window will occupy the entire screen. For example: WINDOW-POSITION IS 8 Note: Data grid columns do not currently support decimal addressing. UNIX/Linux implementations required Thin Client release 6. You can define your own screen modes using the MODE statement. The row and column values can be arithmetic expressions. An attempt to call a screen with a larger window than the defined maximum size for the terminal results in a fatal error. SEARCH expands to all the valid searching possibilities for the screen. where available. PREV. Used to specify a numeric value indicating the size or initial position of the window. The numbers are based on the following grid: 1 2 3 4 5 6 7 8 9 Where 1 means top/left. that is. 1 to 9 The initial position of the window within the container window. the available modes will be displayed and the user must select one. CORRECT and REMOVE. ALLOWED This clause lists all the modes that are allowed with this screen when no modes are specified in the call to the screen. ENTRY. NEXT. CORRECT and REMOVE. REMOVE and SEARCH are only valid if a PRIMARY object or SELECT is specified. If this clause is not specified then no automatic searching. If RELATIVE TO is specified. Windows larger than the normal size cause the screen to change to its wide mode. 32 . If no allowed modes are specified then the screen is only allowed the default modes of SEARCH. FIND. All record searching will be performed using this object. NEXT-SCR. The following predefined modes can be used: SEARCH. PREV-SCR. the window will be displayed relative to these co-ordinates.0 or later. 2 means top/centre and so on. If only one mode is specified then the screen will be placed in this mode automatically. WINDOW-POSITION This clause only has affect if the WINDOW clause is also specified. The following values are currently supported: -1 Run this window in full screen mode. ENTRY. look only for records with the same values as those fields listed. FIND-FORCURRENCY Every allowed mode for this screen that requires currency will have a [Find] mode automatically performed beforehand. The SAME option specifies that when searching. correction. If no fields are listed then it defaults to the fields that make up the specified index. For example. NO-PROMPT-FORSEARCH When search is specified as an allowed mode.reviewing. REVIEW-FROM-START Show records from the start of the file/list onwards when redisplaying the list of review records. index can be specified by the index number (for example. Note: Only the fields listed (as being different) will be returned to the screen. For details on the structure refer to the ‘SELECT Clause’ section. [Prev]. 1) or by listing every field (in order) which makes up the key to the required index. 33 . PROMPT-FORSEARCH Search modes that are normally not shown (for example. A datagrid is generated with moveable button style column headings. [Next]. and do not represent the actual location of the column. insertion or removal of records can take place within the screen. If this option is specified. DATA-GRID This is an enhanced version of a REVIEW screen. If not specified the mode prompts will be displayed at a default position (generally the second bottom line of the current screen or window). the available search modes will be prompted for along with the other allowed modes. The ON INDEX clause forces the object to be accessed only on this index. SELECT An SQL SELECT statement can be specified in preference to a primary clause. A single record in a review screen can be spread over multiple lines. those search modes that can be selected by means of function or arrow keys will not be prompted for. The column coordinate of the ACCEPT and DISPLAY statements that form the columns of the data grid are used for ordering and identification purposes only. allowing columns to be resized and repositioned. show only each different (unique) value of those fields listed. The number of lines per record is defined by the BY clause following the OCCURS. The column headings used are defined by the TITLE clause associated with each ACCEPT or DISPLAY in the DETAIL section of the SCREEN. PROMPT Specifies the position to display the mode prompts on the screen. No other fields in the PRIMARY will be returned. Co-ordinates for the additional lines are relative to the base (first) row specified in the DETAIL section. [Next-Scr] and [Prev-Scr]) will be shown on the mode list. The number of different primary records in the review screen can be specified using the OCCURS clause. If not specified the screen will access the object using index 1. OCCURS 10 BY 2. The fields listed must match either all or part of the leading fields in the key for the specified index. If not specified. The DIFFERENT option specifies that when searching. REVIEW Indicates that this is a review screen. a default number is used. PARAMETERS Allows the definition of parameters that are passed to the routine. It accomplishes this by flagging that all requests for keyboard input will be treated as though <Esc> had been pressed. screen main). WHEN When searching for records. This also applies to screens defined with a SELECT. as the intention of this statement is to stop users from being able to exit the screen by pressing <Esc>. START-ON-CURRENTRECORD If this clause is used in a SCREEN that contains a PRIMARY SAME key. rather than from top to bottom. the file will not be positioned at the start of the key range if the current record is within that key range already. STOP-EXIT-ALL-KEY When F8 (Exit All) is pressed. REVIEW-FROM-END Show records from the end of the file/list backwards when redisplaying the list of review records. RETURNING Allows the definition of parameters that are returned to the calling routine. If the initial routine has a WINDOW specified. to try and allow the programs to back out gracefully. the current record when re-displaying the list of review records. The REVIEW-FROM-END clause can be simulated by a combination of this clause and a SELECT statement with an ORDER BY specifying a DESCENDING order. Not supported on relational databases. All screen output is stopped while in this mode. This is not the same as the REVIEW-FROM-END clause as the REVIEW-BOTTOM-TO-TOP clause reads forward through the list of records and not backwards from the end of the records. The STOP-EXIT-ALL-KEY clause was added to the 34 . The current record is maintained. the 4GL will automatically back out all programs being run by the user. The EXIT-ALL operation will be cancelled if the program executes a BACK-TO-DETAIL statement. For further details refer to the ‘LOCAL Declaration’ section. LOCAL The LOCAL declaration defines fields that are local in scope to this routine. REVIEW-BOTTOM-TOTOP This clause will cause the records in a review screen to be display from the bottom of the review area up to the top of the review area. This clause is only valid if used with a PRIMARY clause. It therefore reverses the orientation of the records on the screen. LEAVE-PARENTSCREEN This clause only has an affect if specified for the initial routine with the program (for example.REVIEW-FROMCURRENT Show the previous screen of records starting at. For further details refer to the ‘PARAMETER Declaration’ section. and including. then this clause is invalid. If the program is called directly from another PRONTO-RAD program using the CALL/SPL statement. where by default the first record shown is the first valid record in the sequence specified by the ORDER BY. the contents of the calling program’s screen will be retained rather than being cleared. allow only records that satisfy the specified condition. For further details refer to the ‘RETURNING Declaration’ section. SCREEN. If only a single colour is specified. NO-REVIEW-ROWSEPARATORS NO-REVIEW-COLUMNSEPARATORS NO-REVIEWSEPARATORS POSITION-ON-OK NO-OK-CANCEL The drawing of separator lines between columns and rows in a review screen can be suppressed with the following clauses: NO-REVIEW-ROW-SEPARATORS. If the screen requires confirmation based on the CONFIRM statement. Any code that loops to stop a user from being able to exit by pressing <Esc> (other than by using the BACK-TO-DETAIL statement) can cause the application to hang if the EXIT-ALL key is pressed. The runtime will automatically display [OK]/[Cancel] buttons when in [Entry] or [Correct] mode of a screen. This only works on review screens. it is assumed to be the background colour. The automatic backout will be cancelled when a routine with this clause specified is encountered. gain focus) when the screen is in [Correct] mode. It only has effect if the EXIT-ALL key is pressed in a child routine. not data grids. it is assumed to be the background colour. When ‘0’ or no colour is specified the user’s default colours will be used. This clause is used for screens that have no primary clause. DOS). as this timeout may not be available on all systems (for example. This should not be relied upon. For example: COLOUR IS RED ON 0 This clause is only valid if the WINDOW clause is also specified (with the exception of the main window). MENU and PROCEDURE declarations to also stop the EXIT-ALL operation. If only a single colour is specified. Clicking the [OK] button is equivalent to pressing F4 35 . They are not shown for entry within a procedure. When the [Entry] or [Correct] mode is selected in a screen. the [Cancel] button will be the default instead of [OK] if the default for the CONFIRM is NO. it will automatically be cancelled. Note: A routine with this clause specified will not stop the EXIT-ALL operation if the EXIT-ALL key was pressed whilst in the routine. the screen’s modes are hidden and the [OK] and [Cancel] buttons are displayed in the centre of the line used by the modes. The REVIEW COLOUR clause can be used in a review screen to specify the background colour for the review area. a 10 second limit is placed on the EXIT-ALL operation by PRONTO-Xi. Any routines that contain this type of code should either be rewritten or specify the STOP-EXIT-ALLKEY clause to avoid this problem. If the EXIT-ALL is still in effect after 10 seconds. NO-REVIEWCOLUMN-SEPARATORS. The POSITION-ON-OK clause for a screen indicates that the [OK] button should be positioned on initially (that is. As a fail-safe. and NO-REVIEW-SEPARATORS (the latter suppresses both). COLOUR or COLOR The COLOUR clause is valid for a SCREEN/MENU/PROCEDURE to specify the default window colours. for example a report parameters screen. . rather than the first ACCEPT. search. EXPORT Indicates that the routine is an entry point to an operations table when used as a component library. the VALIDATION section of all ACCEPT fields will be processed. This is performed once at the start of the screen and whenever the screen is refreshed using the REFRESH statement. headings). When [Entry] mode is invoked. The [OK]/[Cancel] buttons are not shown on a window that is less than four lines deep. BEFORE Specifies the BEFORE command group. They can still be clicked on when a sub-screen is being processed. This command group should contain ACCEPT statements for the entry/specification of field values. The [OK]/[Cancel] buttons replace the confirmation question in this situation. ACCEPT. A screen in [Correct] mode that does not have a PRIMARY defined is assumed to be an options/defaults screen. in that any field can be navigated to. This is performed once when exiting the screen. even in [Correct] mode. On exiting [Entry] mode. The screen area associated with a DISPLAY. Sub-screens that inherit the window of the calling routine will not give focus to the [OK]/[Cancel] buttons. This should contain any setup code for the screen (for example.(Confirm). The NO-OK-CANCEL clause can be used on a screen to disable this functionality. etc. The screen will then operate the same as [Correct] mode. The WHEN clauses for all statements in the screen are evaluated each time screen input is requested. AFTER Specifies the AFTER command group. Only the screen that defines the current window can gain keyboard focus on the [OK]/[Cancel] buttons. TITLE The TITLE clause is available for any MENU/SCREEN/PROCEDURE with a window. A FORM-ENTRY screen with an ACCEPT with FILL WITH TRAILING specified will always have the trailing character added to the current field value whenever the ACCEPT is processed.). DETAIL This contains the iterative code for the screen. The [OK]/[Cancel] buttons will only gain focus for keyboard entry if the screen would normally ask for confirmation for entry/correct. etc. This will set the title on the title bar of the window. This code is performed for every screen operation (for example. It is processed once only upon entry to the routine. For further details refer to the ‘EXPORT Clause’ section. entry. all ACCEPTed fields will be set to their default values. USER-TRIGGER This clause is similar to the EXPORT clause described 36 . FORM-ENTRY When this clause is specified. This should contain any finalisation code for the screen. the [Entry] mode of the screen is processed differently to the traditional sequential entry. In this situation the [OK] button will initially have the keyboard focus. Clicking the [Cancel] button is equivalent to pressing <Esc>. with a WHEN clause will be greyed if the WHEN condition is false. That is. Parameters for a routine can be defined as a completed row/record for an object. When multiple versions of the same component library are referenced (that is. In this circumstance the procedure will be the first performed for the program regardless of its location in the program. The row co-ordinates for the first ACCEPT or DISPLAY statement identifies the first row of the review area. If neither is specified then CAN-OVERRIDE is currently assumed. The names of EXPORT routines must be unique between all component libraries attached to a program. each unique component library is attached separately. MODE. Row coordinates outside the review area can be specified in the DETAIL section of a review screen. RE-SELECT Common Clauses The following clauses are shared by a number of PRONTO-RAD declarations and statements:  EXPORT Clause  SELECT Clause EXPORT Clause A PRONTO-RAD component library is an operations table designed to contain a group of routines that are directly callable but independent from a controlling program. the first ACCEPT or DISPLAY statement cannot have an expression for the row coordinate. For further information refer to the ‘Row/Object Parameters’ section. PROCEDURE and API. Marking these routines with EXPORT within the component library program indicates that the routine is an entry point to an operations table when used as a component library. Multiple LINK statements can be specified and can refer to an already specified component library. EXIT. Notes Each unique component library has its own set of data per attachment to the controlling program. Absolute row coordinates are allowed in a REVIEW screen. Component library names are specified in the same manner as standard PRONTO-Xi programs when these are invoked (for example. then “$CUS/deb/m10shl” and “$BMS/deb/m10shl” are attached separately (each with their own data). API. can be marked with the EXPORT clause. Notes There is a special case where the name of the screen is ‘main’.above. Data is not shared between the controlling program and any attached component library. the name of an EXPORT routine cannot occur in different named component libraries. For example if “deb/m10shl” is contained in both $CUS and $BMS. other than via parameter passing and returning. A component library can reference routines in other component libraries. The full path names should not be specified. This statement specifies the names of the component libraries containing routines referenced by the program. As a consequence. data is not shared between 37 . A single component library is only attached to the controlling program once even if it is referenced by other component libraries. Any ACCEPT or DISPLAY statement that specifies a row outside the review area will function as in a normal SCREEN. but additionally permits the routine to be called as a component library trigger by the Screen Customiser. Similarly. DO. MENU. Syntax Clauses EXPORT|USER-TRIGGER [CAN-OVERRIDE|NO-OVERRIDE] CAN-OVERRIDE NO-OVERRIDE These clauses can be specified for a routine’s definition after the EXPORT clause to indicate if the routine is allowed to be overridden by custom component versions. “deb/m10shl”). PROCEDURE. Various declarations (routines). See Also MENU. The LINK statement is used to attach a component library to a program. custom/override versions). for example SCREEN. A program can reference routines in multiple component libraries. This is achieved by having multiple directories specified in PROPATH that each contain the same named component library. API. there can only be one transaction active. LINK For further information refer to the ‘Component Libraries’ section of the 4GL User Guide. See Also MENU. To override these routines. If a component library wishes to directly invoke only the local version of an EXPORT routine (that is. That is. The same transaction control is applied across the controlling program and all attached component libraries.. as well as client specific customisation. it must use the DO LOCAL statement. it must manually pass control onto the next level of the routine. These routines must be structured to work as standard component library entry points. Overriding Standard Programs: The component library mechanism can also be used to override specified routines in standard PRONTO-Xi programs that are designed to allow this. Note: The ‘main’ routine must have EXPORT specified. 38 . The override program would have a ‘main’ routine that issues the “DO NEXT main” statement to pass control to the standard program’s ‘main’ routine. That is. There are however some differences from SQL syntax due to the nature and structure of the Pronto Software 4GL implementation. PROCEDURE. That is.different component libraries. Only the EXPORT routines that are intended to be overridden need be defined in the custom version of a component library. To only affect files in the current operations table the LOCAL clause should be specified with the ALL clause. When invoked. The controlling program and all attached component libraries share the same current working directory. If an override version of an EXPORT routine exists then the base (distribution) version will not be invoked unless the override version explicitly passes control to it via the DO NEXT statement. SCREEN. The CLOSE ALL and UNLOCK ALL operations by default impact the controlling program and any attached component libraries. a custom program of the same name would be placed in $CUS. etc. The SPL/CALL statement without the LEAVE-FILES-OPEN or EXTERNAL clauses will issue a CLOSE ALL that will affect the controlling program and any attached component libraries. unless an override of the routine intends to be a complete replacement for the routine. Any EXPORT routine invoked within the $BMS version will perform the $CUS version of the routine (if present). the one defined in that component library). SELECT Clause The SELECT clauses supported by the PRONTO-RAD 4GL language are based substantially on industry standard SQL syntax. This enables support for localisation. Override (Custom) Component Libraries: It is possible to have a layering of custom component libraries that override the same EXPORT routine. Any change to the current working directory will affect the controlling program and all other attached component libraries. CLOSE ALL LOCAL and UNLOCK ALL LOCAL. This is achieved by specifying the EXPORT clause on the routines allowed to be overridden within the standard $BMS program. Transaction commands issued will affect the controlling program and all other attached component libraries. This option must be used with extreme care as you will potentially bypass essential logic in an overridden version of the routine. the version of the program in $CUS would be executed as the controlling program and refer to the $BMS version as a component library. Fields of the same name referenced in the controlling program are independent to that of the same field referenced in any of the component libraries. The value of fields that are not listed in the select-list will not be affected by the SELECT statement. A select-list can be formed by specifying individual fields from the objects in the FROM clause. if a field called ‘calc’ was defined within the program: SELECT accountcode.]] [GROUP BY field-list] [HAVING condition] Clauses select-list The select-list is the list of fields (columns) to be included in the rows returned (the result set). deb-master..] [ORDER BY field-name [DESC] [field-name [DESC] . or wildcard selection. Any fields referenced within the calculation must be either contained in one of the object in the FROM clause. shortname FROM deb-master WHERE balance > 1000 DETAIL DO my-procedure END-SELECT // balance will still be 10 39 . a calculation field. For example. Syntax SELECT [DISTINCT] select-list FROM object-list [WHERE condition] [ORDER BY field-name [DESC] [field-name [DESC] .. the result will be returned to the non-prefixed version of the field within the application (for example. If a field is specified with an object prefix.. For example. Calculations can be specified in the select list. For example: SELECT * FROM deb-master Note: Only the fields listed in the select-list (either explicitly or by a wildcard) will be returned to the application.accountcode will return the value into accountcode). The field used to store the result of the calculation must be a field already defined within the program. or a host field (see later). accountcode or deb-master... selecting deb-master. regardless of whether they occur in one of the objects in the FROM clause.*” (for example.*). the value of ‘balance’ within the application is not affected by the following: SET balance = 10 SELECT accountcode.accountcode). calculations. calc = balance * 10 To wildcard the selection of all fields within a specific table you specify the object name followed by “.]] [GROUP BY field-list] [HAVING condition] [FOR UPDATE] SELECT select-list FROM object-list [WHERE condition] UNION [ALL] SELECT select-list FROM object-list [WHERE condition] [UNION [ALL] . To wildcard the selection of all fields within all objects specified in the FROM clause.. Individual fields can be specified with or without the prefixed name of the object that they occur in (for example. a single “*” can be used.The clauses defined here can be used within the SELECT loop statement and within the SELECT clause of a SCREEN definition. if included. Both the WHERE and HAVING clauses can be used within the same SELECT. For example: GROUP BY rep-code territory This will return one row for each unique rep-code and territory combination. but can be reversed using the DESC option. All selected rows will be locked when used with a SELECT loop. This clause is only valid for a single object SELECT. Records will only be locked when a MODE is selected that requires a lock. For example. One aggregate row is returned for every set (group) of rows with the same values for the fields specified in the GROUP BY clause. This is based on the values of all fields that form the select-list. See Notes below. FOR UPDATE is assumed for a SCREEN that uses SELECT * from a single FROM object. The HAVING condition can only reference aggregate functions or the fields listed in the GROUP BY clause. the order of rows returned in the result set cannot be guaranteed. The field values are sorted in ascending order by default. ORDER BY Rows are returned in the field sequence specified in this clause. If no ORDER BY or GROUP BY clause is specified. The select-list must only specify the fields listed in the GROUP BY clause. may affect performance if there is a large result set. WHERE Only rows that fulfil the condition (logical expression) specified will be returned. GROUP BY If this clause is specified then the SELECT statement is an aggregate query. HAVING This clause is used to exclude groups of rows defined by the GROUP BY clause. The HAVING clause is used to restrict the resultant groups. when the SELECT is used with a SCREEN. 40 . FROM List of PRONTO-Xi objects (tables) that the fields (columns) are selected from. All fields should be selected (with an asterisk “*”). my-calc = SUM(tr-amount) FROM deb-trans WHERE trans-type = "IN" GROUP BY accountcode HAVING SUM(tr-amount) > 1000 FOR UPDATE or FOR-UPDATE This clause indicates that the rows extracted can be updated or deleted. The WHERE clause is used to restrict rows that make up the set used by the GROUP BY. This clause.DISTINCT Duplicate rows will not be returned in the result set. and/or the results of aggregate functions (see later). the following would return the accountcode value where the total of the tr-amount field for the ‘IN’ records in that accountcode exceeds 1000: SELECT accountcode. Note: If aggregate functions are specified in the select-list and no GROUP BY clause is specified. then they all must be numeric in that column). The expression specified must be numeric. otherwise trailing spaces will be included as part of the pattern. For example: SELECT * FROM sales-order WHERE so-invoice-no = :lf-invoice-no UNION ALL SELECT * FROM sales-order-archive WHERE so-invoice-no = :lf-invoice-no ORDER BY so-invoice-no Aggregate Functions When a GROUP BY is used. or if you believe that there should not be any. Using the ALL keyword will generally improve the performance of the query.UNION [ALL] The UNION clause allows you to combine the results of multiple SELECT statements into the one result set. if one is numeric. etc. date. The expression can be any type (for example. You can only specify a single ORDER BY clause. alphanumeric. The data type of each corresponding column must be compatible (for example. General: When a LIKE comparison is used in a WHERE clause and the comparison is required with the pattern stored in a host field. The optional ALL keyword means that duplicate rows are allowed (that is. numeric. MIN (expression) Returns the minimum (lowest) value of the results of expression within the rows that make up the current group. the entire set of valid rows will be considered as a single group. MAX (expression) Returns the maximum (highest) value of the results of expression within the rows that make up the current group. There is no limit to the number of SELECT statements that you can join together with UNION statements in a query. The same number of columns MUST be selected in each SELECT statement. These are functions that return the accumulated result for all rows in the current GROUP BY set. The names of the columns do not need to be the same. SUM (expression) Returns the sum (total) value of the results of expression for the rows within the group. This clause must be at the end of the query if used. The column names that you use are those of the first SELECT in the query. The expression can be any type (for example.). numeric. Multiple objects in the FROM clause: 41 . COUNT () Returns the number of rows in the current group. The expression specified must be numeric. alphanumeric. Notes AVG (expression) Returns the average value of the results of expression for the rows within the group.). the select-list and the HAVING condition can reference aggregate functions. It should be used if you do not care if duplicate rows are returned. a result row with the same values for all columns selected). In this case the SELECT will return one aggregate row for the entire query. This may be useful to combine the results of a ‘live’ file with that of an archive file (for example. sales-order and sales-orderarchive). that field must be defined with type STRING. date. etc. For example: SELECT acc1 = deb-master. by default an “auto-join” will be performed on this field if it occurs in the select-list. For example. even if there is no valid row for the join to this object. deb-trans An auto join would NOT be performed for the following since no selected field exists in both objects: SELECT shortname. shortname. then individual field relationships must be specified explicitly in the WHERE clause. This should occur directly before the object that the outer join is to be performed on. For example: FROM deb-master.The result of a multiple object (table) query is a set of rows that combine (join) all of the valid rows in all of the objects selected. if the field “accountcode” was selected and both “debmaster” and “deb-trans” which contain this field were specified in the FROM clause. This is provided for SQL compatibility only. acc1 = deb-trans. NOTE: An auto join is not performed if the field is not selected within the select-list (either explicitly or via a non-prefixed wildcard). The optional ON keyword can also specify the join relationship between the objects. It may also be necessary to assign them to a calculation if the same field is required in the result from multiple tables without a join. With an outer join. The simplest way is to use the word OUTER within the FROM clause. deb-master.accountcode = deb-trans. OUTER deb-trans An alternate way of specifying an outer join is by the OJ keyword of the FROM clause.accountcode. stock-movements WHERE cre-accountcode = stk-accountcode Auto joins: When multiple objects are specified in the FROM clause. deb-trans Outer (optional) joins: An outer join can be specified between objects in the FROM clause. and should be avoided. If an auto join is not performed. any non-join fields in the outer object will be set to their blank value if there is no valid join row. tr-amount FROM deb-master.accountcode An auto join would be performed for the following: SELECT accountcode.accountcode If this relationship is not required then you must ensure that the field(s) are selected (or referenced) individually with an object prefix (for example. of which most are not required.accountcode). Outer joins can be specified in one of two ways. and numeric fields will be set to zero. For example. a row will always be returned from the outer object. Alpha fields will be set to spaces. The format is: 42 . A normal (inner) join will not return a result row if there is no matching record in both joined objects. This is seldom what is required. if there is no deb-trans record for the matching deb-master record. the following would be implied: WHERE deb-master. the result will be the Cartesian product of all the rows in all of the tables listed. An auto join has the same effect as if there was an explicit join specified on this field in the WHERE clause. In circumstances where the join is based on a field that has the same name in each of the tables to be joined. The relationship between the tables can be defined in two ways. an implied “auto join” can be used (see below). If no criteria are given to define the relationships between the tables (that is. how they are to be joined). In this circumstance. tr-amount FROM deb-master. SELECT * FROM cre-master. If you wanted a result row returned even if there are no deb-trans rows for an accountcode you would use an outer join. and the same field name occurs in more than one of the objects. as it will result in a potentially significant amount of rows being returned. For example. ]]} For example: SELECT * FROM {OJ deb-master LEFT OUTER JOIN deb-trans ON deb-master. This is a PRONTO-RAD 4GL concept. Host fields that are not calculations are considered static and should not change values during the enquiry. The use of this is not recommended. the objects will be processed in the order that they are listed in the FROM clause..is” option of the 4GL debugger can be used at runtime to analyse the way in which the SELECT statements are being processed. indexes used. An information window will be shown for each SELECT statement that gets processed (including any screen with a PRIMARY).  Table aliases cannot be specified within the FROM section. if “lf-accountcode” contained the required “accountcode” value then the following could be used to select all records with this value: SELECT accountcode.accountcode} Forcing the use of an index: The preferred index to use when processing an object can be specified by issuing the “ON INDEX” clause directly after the name of the object in the FROM list. sorting etc. Main differences between the 4GL and SQL SELECT syntax: See Also  Auto joins do not occur in SQL. ranges.  There is no concept of a NULL value for a field within PRONTO-Xi. PRONTO-RAD supports the following statements: ABORT ENQUIRY RE-ENTER 43 .  Commas are used only for readability and are optional. SELECT. RE-SELECT Statements Statements are basic elements used within the PRONTO-RAD 4GL language. A LIKE object should be declared within the application to accomplish the same result.field1 = object2. This information is not available at compile time as the final determination of how a SELECT will be processed is performed at runtime. Host fields can only be selected (that is. in the select-list) if they hold the result of a calculation. SCREEN. Long term support for this clause is not guaranteed.accountcode = deb-trans. :trans-type).{OJ object1 LEFT OUTER JOIN object2 [ON object1. For example.. This identifies the object extraction order. These fields are called host fields. This will refer to the current value of “trans-type” within the application program. The IS NULL test is not supported.field2 [AND . Host fields: Fields that are not contained in the objects specified in the FROM clause can be referenced in the enquiry.  Nested SELECT statements (sub-queries) are not currently supported. joins. tr-amount FROM deb-trans WHERE accountcode = :lf-accountcode It is possible to reference fields contained in the FROM objects as host fields prefixed with a colon (for example. If this is used. and not to the value of that field/column in the current row being accessed within the table.  The assignment of calculations is specified differently. A host field that does not store the result of a calculation should be prefixed with a colon (:) to ensure that it cannot be confused with other fields in the FROM objects. as unpredictable results may occur. Analysing the processing of a SELECT: The “. This should only ever be done if there is no chance that the SELECT will return a row that contains a different value for this field. They can however occur (as entry only) in most sections of code (for example. ACCEPTs are principally designed to be placed in the DETAIL section of a SCREEN where they are used for data entry and correction. 44 . a BEFORE section of a screen). Syntax ABORT expression [PIC [IS] picture-string] . WHILE or EXTRACT loop. Clauses PIC IS See Also MESSAGE. SPL Override the default display format of the preceding expression. . ACCEPT Statement This statement specifies the displaying and entry/correction of a field within the current screen. .ACCEPT EXIT RE-SELECT ACKNOWLEDGE EXTRACT REFRESH AUDIT EXTRACT-NOTES REPEAT BACK-TO-DETAIL FOR REPORT BEGIN-WORK GET REPORT-SECTION BOX IF RESTORE BOX-CHAR INITIALISE ROLLBACK-WORK BREAK INSERT SAVE CALL LINK SELECT CHECK-BOX LOCK-METHOD SERIAL CLEAR MESSAGE SET CLOSE MESSAGE-BOX SKIP COMMAND NEED SPL COMMIT-WORK OPEN STATEMENT-GROUP CONFIRM OPTION STRING CONTINUE PAGE SWITCH CONTINUE-ENTRY PAUSE TRANSACTION DELETE POP UNLOCK DISABLE-ALL-TRIGGERS POSITION UPDATE DISPLAY PRINT VERSION-NUMBER DO PUSH WHILE END-OPTION QUERY END-STATEMENT-GROUP RADIO-BUTTON ABORT Statement Displays a message on the screen and then aborts the program after the message has been acknowledged. This is intended for error conditions only. An ACCEPT statement can also be included in a FOR. An error status will be returned to the calling 4GL program (if present). field alpha-literal ...] [LOWERCASE|UPPERCASE] [LEFT|CENTRE|RIGHT|CENTRE-COORD|RIGHT-COORD] [HELP [IS] expression] [BOLD] [DIM] [FLASHING] [INVERSE] [ITALIC] [UNDERLINED] [FOREGROUND] [BACKGROUND] [BLANK] [ON ERROR procedural-statements END-ON] [ON function-key procedural-statements END-ON] HELP-CONTEXT [IS] help-file-expression context-id-expression [HELP-SCREEN PRIMARY object-name @row.col [TITLE|COLUMN-TITLE [IS] alpha-expression [@row..Syntax ACCEPT field-name @row.col]] [NO-TITLE] [PIC [IS] picture] [BLANK-WHEN-ZERO] [BLANK-DECIMALS-WHEN-ZERO] [OPTIONAL] [DEFAULT [IS] expression] [ALLOW expression [TO expression] .] [JUSTIFY] [AUTO-RETURN] [TIME-OUT [IS] seconds] [EDIT[S] [IS|ARE] edit ....] [FILL [WITH] [LEADING|TRAILING] alpha-character] [LOOKUP [NOT] [IN] object-name [ON INDEX index] [KEY [IS] expression .] [DISALLOW expression [TO expression] ...col [OCCURS number-of-lines] SHOWING field alpha-literal [...] [USING field]] [WHEN condition] [SHOW-VALUE] [NO-CLEAR] [SUPPRESS] [READ-ONLY] [FIXED-WIDTH-FONT] [COLOUR [IS] colour [ON colour]] [BEFORE-ACCEPT procedural-statements END-BEFORE-ACCEPT] [VALIDATIONS procedural-statements END-VALIDATIONS] [procedural-statements] [SCALE [IS] expression] [ON CHANGE default-value END-ON] 45 . 0 or higher this can be an expression that is evaluated at runtime.bmp" @10. that area includes a full character cell position to the bottom right of the end co-ordinate.0. The amount of characters being displayed (or entered) is based on the definition of the field. These clauses cannot be used in conjunction with a PICTURE clause.999.20 The above example occupies an area of the screen from @10. NO-TITLE The dictionary defined title for the field is not to be used. Intended for future use. in the heading for a column. Whilst decimal places are supported. if the decimal places are zero. top/left) is @1.5.10 PIC X(20) The above example occupies an area of the screen from @10.2 Row/column values less that 1. DISPLAY ws-text @10.999. For example: @10.0 to @23.1 not @0. The BLANK-WHEN-ZERO clause generates a PICTURE that will display blanks if the value is zero. DISPLAY BITMAP "abcd. TITLE or COLUMN-TITLE Title for field.0 to @10.col Screen co-ordinates for field.10.9999 WINDOW @1.30. or to the left of the field for a normal screen). Decimal places are supported within the co-ordinates.5 PIC X(20) The above example occupies an area of the screen from @10. The amount of characters displayed will depend upon their size. BLANK-WHENZERO. If only one set of co-ordinates are specified for the ACCEPT then the prompt will be positioned relative to this location (for example.4999.999. Unless other specified. the co-ordinate addressing is still based on a character grid. Note: If a variable expression is used then the value must be set in the BEFORE section or prior to the SCREEN being invoked.31. BLANKDECIMALSWHEN-ZERO The BLANK-DECIMALS-WHEN-ZERO clause generates a PICTURE that will display blanks where the decimal places would normally be displayed.10.80 The above example refers to an area from @1. when an area of the screen is addressed. Both the row and column values can be arithmetic expressions. A PICTURE on a DISPLAY or ACCEPT will adjust the amount of space used by the field on the screen.0. For example.999.Clauses @row. Note: The co-ordinate for the origin of the screen (that is.5 to @11.4999. PICTURE or PIC Override picture for displaying and accepting the field.0 are invalid.19. For version 6. it is possible to display a 30 character field when a PIC X(20) is specified.10 to @14. For example: DISPLAY ws-text @10.9999.10.1.5.0.5.1 TO @23. 46 . but will not limit the amount of characters being displayed (or entered).80.10 TO @14.20. If a partial field list is used for the ON INDEX clause. This is equivalent to writing FILL WITH LEADING SPACES. If no value is entered then the field will be set to zero if numeric or spaces if alphanumeric. Although not recommended. OPTIONAL The entry of a value when in [Entry] mode is optional. LOOKUP After a value has been entered lookup the specified object. the operation will act as though the real index only contained the specified fields. If NOT is used. By default. This option is only available if the field is of type ALPHA or STRING. FILL WITH If LEADING is specified then the value entered will be right justified and leading blanks filled with the specified character. The index used will be the first index found with the specified leading fields. If no value is entered then the default value specified will be used instead. A field list if specified only needs to match the leading fields of a valid index. JUSTIFY Right justify the value entered. If the lookup fails then the value entered is invalid. Only alphanumeric fields can have edits applied to them. 47 .FOREGROUND/ BACKGROUND Display this field with the specified foreground/background attribute for the terminal type. if no attribute is specified either the FOREGROUND or BACKGROUND attribute will be applied to the field being ACCEPTed. The operation will act as though the real index only contained the leading fields that correspond to the number of key values specified. If TRAILING (or neither) is specified then the un-entered part of the value (trailing blanks) will be filled with this character. Values do not need to be specified for each of the fields in the index used. DEFAULT The entry of a value when in [Entry] mode is optional. This option is only available if the field is of type ALPHA or STRING. DISALLOW The user will not be allowed to enter values in the specified range or ranges. The currently available edits are: 1 Right justify trailing numeric characters within field’s actual size or override picture if present. BACKGROUND is the default for ACCEPTs in the BEFORE section of a SCREEN or MENU. LOWERCASE/ UPPERCASE Map any characters input to their uppercase/lowercase equivalent. then the value entered is invalid if the lookup does not fail. EDITS List of all edits that the value entered must comply with. ALLOW List of allowable values that can be entered for the field. FOREGROUND is the default for all other ACCEPTs. it is permissible to use both an ALLOW and a DISALLOW clause in the same ACCEPT statement. the ACCEPT will continue on as if the <Enter> key had been pressed. 48 . BOLD DIM FLASHING INVERSE ITALIC Valid for version 6. WHEN Only allow entry/correction of the field when the condition is satisfied. Flashing will apply PROClient colours and will default to left align. HELP-CONTEXT Allows for the specification of the help file name and ID for context sensitive help. HELP Defines a help line for the field. This allows for the overlaying of ACCEPTed fields on the screen. The LEFT clause causes text to be left justified (this is generally the default). This is useful for password entry etc. but can be used on fields of any length. The function keys which can be specified are: UP-ARROW DOWN-ARROW LEFT-ARROW RIGHT-ARROW HELP-KEY Several ON function-key clauses can be defined within a single ACCEPT statement. ON ERROR Procedural statements to perform if the value entered fails either a LOOKUP or it is not in the ALLOWED value range. The RIGHT clause causes text to be right justified within the field rather than left justified. SHOW-VALUE The current value of the field will be shown when the ACCEPT is executed and the WHEN clause is not satisfied. The value of the field is left unchanged. The CENTRECOORD indicates that the co-ordinate represents the centre of the field (and also centres the text within the field). This can be used to override the field’s help context information defined in the dictionary or to specify it for nondictionary based fields. then the ON ERROR section of the ACCEPT statement will be activated.1 or higher.1 or higher. The ACCEPT statement must have an ON ERROR section. TIME-OUT Indicates that if no input occurs in the specified number of seconds. Dim does nothing. ON function-key Procedural statements to perform if the specified function or arrow key is pressed. If the condition is not satisfied then no value will be shown for this field unless the SHOW-VALUE clause is also specified.LEFT CENTRE RIGHT CENTRE-COORD RIGHT-COORD The CENTRE clause causes text to be centred within the field rather than left justified. Bold. No error message will be displayed for the error since this means that you are handling the condition. Unless a RE-ENTER statement is present in the procedural statements the value will not be forced to be re-entered. italic and underline will apply the appropriate windows font. Note: Not available in version 6. Inverse will default to centre align. AUTO-RETURN Indicates that once the user has entered the maximum number of characters for the field. NO-CLEAR The area on the screen used by this ACCEPT will not be cleared if the WHEN clause is not satisfied. The RIGHTCOORD indicates that the co-ordinate represents the far right position of the field (and also right justifies the text within the field). This is primarily intended for single character fields. BLANK Do not echo (display) any characters entered for this field. For example: ACCEPT sys-comp-code @6. If a client removes the suppression attribute for the field. This also applies to fields suppressed or made read-only by the client as an override. It does not require row or column co-ordinates to be defined within the ACCEPT. In [Entry] mode. using field names then the accept variable name must be defined with a ‘like’ definition. FIXED-WIDTHFONT This clause causes the font used to be the fixed width font defined. The OCCURS if specified determines the number of review lines to be displayed. If no OCCURS is specified then the number of lines displayed will be determined automatically. it must also supply a valid row and column value if there is not one defined already. If the field being ACCEPTED does not occur in object-name.HELP-SCREEN This will generate an automatic review screen to look for field values when the HELP key is pressed. The coordinates specify the top left corner of the screen.2 DEFAULT sys-comp-code UPPERCASE HELP-SCREEN PRIMARY system-companies @5. it is still processed in [Entry] mode (although there is no user interaction). The user can use PRONTO-Xi Screen Customiser to unsuppress it A SUPPRESSed field is not shown on the screen. If you want the accept name to be different from the default. A suppressed field is still processed in [Entry] mode (although there is no user interaction). The screen will display records from object-name. A READ-ONLY field is shown similar to how it would have been shown on the screen if a DISPLAY statement was used instead of an ACCEPT. rather than the variable (proportional) width default. The user can use PRONTO-Xi Screen Customiser to change the READ-ONLY attribute. if there is no default specified for the field. and show each of the fields listed. SUPPRESS This field is suppressed in normal mode. the USING verb can specify an alternative field whose value is to return in its place. However. the field will be set with its standard ‘null’ value (for example. The SUPPRESS/READ-ONLY clause on an ACCEPT also implies the OPTIONAL clause. which must have a DEFAULT clause. zero or spaces).30 OCCURS 10 SHOWING sys-comp-code "Company" sys-comp-desc "Description" USING sys-comp-code Note: The USING clause must match the ACCEPT clause. 49 . READ-ONLY This field is read only by default. All validations defined for the accepted field are applied to a suppressed or read-only field. PRONTO-Xi will attempt to select a bold (thick) version of the font with the required scaling. A field type of COLOUR (for example. These statements are usually for extra data validations. proceduralstatements Procedural statements following an ACCEPT are always executed after the ACCEPT is processed. 100 percent) is normal. When in [Correct] mode.. A scale of 100 (that is. If the BOLD attribute is also specified in the DISPLAY statement. as the width of individual characters varies within the font. 50 . Note: It is executed AFTER the WHEN clause before the ACCEPT is evaluated. Note: Proportional fonts base their size on their height and not their width. When this clause is used in a DATA-GRID. This section is not executed if the ACCEPT is processed as a result of a RE-ENTER operation.. The syntax of the clause is: DISPLAY .1 SCALE IS 300 Note: This clause is ignored if the field being accepted forms part of a data grid. For example: COLOUR IS RED ON 0 The standard PRONTO-Xi/PROCLIENT colours are supported (as per File -> Settings -> Color). The colours can be specified as an expression (and hence can be varied at runtime). these statements (and the ACCEPT itself) will only be performed if the SELECT key is pressed. A scale of 50 is half size and 200 is double. COLOUR or COLOR For example: COLOUR IS RED ON BLACK COLOUR IS BLUE When ‘0’ or no colour is specified the user’s default colours will be used. The statements contained here will not be executed when the screen is in search/show modes (that is. individual cells can have separate colours specified (by using an expression for the colours).BEFORE-ACCEPT END-BEFOREACCEPT A BEFORE-ACCEPT section is available for an ACCEPT. This section is performed prior to the field being entered/corrected. but need not be. TYPE IS COLOUR) can be used. etc. It is not performed in any of the search modes. Either the foreground or the foreground and background colours can be specified. when searching or during a refresh). VALIDATIONS Procedural statements to perform after a value has been entered (and has passed all other automatic validations). Fields storing colours must be at least PIC 9(5). They will not be executed by arrow keying over the ACCEPT. SCALE Allows the scaling factor of the font used within the DISPLAY statement to be altered. SCALE [IS] expression For example: DISPLAY "Hello world" @1. however. This means that the value displayed may be out of alignment with other values displayed. but the whole (integer) portion of the number can be displayed in the space provided by ignoring the decimal places. SHOWING clause of HELP-SCREEN can specify field prompts. See Also DISPLAY. if the user presses the HELP key on an ACCEPT that contains an ON HELP-KEY section. For example: HELP-SCREEN PRIMARY deb-master @10. When specified for a RADIO-BUTTON or CHECK-BOX. REFRESH 51 . If the value to be displayed is too large for the PICTURE specified. RADIO-BUTTON and CHECK-BOX statements are within a FORM-ENTRY screen. The field list of the SHOWING clause can include the prompts to be displayed for the fields. The program logic must fall through to the ACCEPT for it to be executed. RE-ENTER. You cannot arrow key forward. A negative value shown with an unsigned picture will also be shown as a set of question marks.ON CHANGE This section is only available if the ACCEPT. Automatic invocation of help screens on failed LOOKUP: If an ACCEPT has a LOOKUP clause as well as either an ON HELP-KEY section or HELPSCREEN specified. The same applies to the HELP-SCREEN clause of the ACCEPT statement if it is used. This occurs regardless of the previous value of the fields. This section will be automatically invoked at the beginning of [Entry] mode when the initial value of the fields are set to their default values. Notes ACCEPT statements that occur within conditional code (for example IF or WHILE statements) are fully supported. the code within this section will now be performed. The code in the ON ERROR section is intended to handle the failed LOOKUP. Any validations will always be performed prior to the ON CHANGE section. then the ON CHANGE section will not be invoked. The prompt for a field can be specified directly after the field’s name.10 SHOWING accountcode "A/C". Should any validations fail. shortname "Name" Overflows of displayed fields shown: A field/expression DISPLAYed or PRINTed that is too large for its default (or specified) PICTURE will be shown as a set of question marks (though there is an exception). this section will be invoked immediately when the user changes the value of the radio button or check box. Whenever the value of a field changes this section will be invoked. a failed LOOKUP with automatically cause the ON HELP-KEY section or HELP-SCREEN to be invoked. This does not apply if there is an ON ERROR section in the ACCEPT. then the value will be displayed without decimal places. ACCEPTs in conditional code are processed in [Entry] mode style. it does mean that the value is still visible. The prompt must be specified as a single alphanumeric string enclosed in quotes. The WHEN clause is still the preferred way to make an ACCEPT conditional. ON HELP-KEY section processed during a FIND: During a FIND operation. you can only arrow key to the previous ACCEPT. You cannot arrow key to an ACCEPT in conditional code. If multiple objects refer to the same physical file. Any objects in the current set that were not listed in the AUDIT OFF statement will still be audited. AUDIT Statement This statement controls the automatic audit logging of changes made to one or more objects.] object-name This is a list of one or more objects required in the audit trail. then any changes made to these objects after the execution of this statement will be written to a log file. The first form turns auditing on. The statement has two forms. then auditing is turned off for all objects. Auditing on all other objects that match the base LIKE object of the audited object will be flagged. Objects opened as TEMPORARY are never audited. For example.. Note: The Audit Management (SYS X018) folder contains complete audit file management and viewing functionality. This only occurs for objects that are of the same type as the audited object and that at the point that the AUDIT statement was invoked had the same file/table name associated with the object. Audit information can only go to one log file. A window will appear which contains the message and a prompt to ask the user to enter ‘Y’. the same number of AUDIT OFF statements specifying this object must also be executed to turn auditing off for this object. all future audit log information will be written to the new log file.] [TO alpha-expression] AUDIT OFF object-name1 [object-name2 . If the AUDIT ON specifies a log file name different to the one currently in use. rather than resetting any previous list. If multiple AUDIT ON statements are executed for the same object.ACKNOWLEDGE Statement The ACKNOWLEDGE statement is a means of forcing the acknowledgement of a message.. deb2 or deb-master would result in the others being automatically audited.log is used. if deb1 was declared “like deb-master” and deb2 was declared “like deb1”. the AUDIT statement can still be specified within applications. Syntax ACKNOWLEDGE MESSAGE [PROMPT [IS] prompt] Clauses PROMPT Prompt to display when asking for acknowledgement. However. Note: The AUDIT statement can still be specified within applications when dictionary-based 52 .. If no TO clause is specified. The AUDIT OFF statement allows for a list of objects. OFF Turn audit logging off. Notes If multiple ACKNOWLEDGE statements occur together then the messages will be concatenated and shown within the same window. The second form specifies that auditing on one or more objects should be turned off.. TO alphaexpression This is the file name to use for the audit trail instead of the default. No other response is allowed. The AUDIT ON statement adds the objects specified to the set of objects currently being audited. then all these objects should be specified in the audit log. Syntax Clauses Notes AUDIT [ON] object-name1 [object-name2 . If objects are specified then these objects will be removed from the set currently being audited. then auditing any of deb1. Any changes made to an object prior to turning on audit logging will not be written to the log file. An AUDIT OFF with no object list cancels all auditing. and the control of what is audited should be primarily controlled by the object and field definitions in the dictionary. If a list of one or more objects is specified. The entry in the Audit log will reflect the name of the base like object. If not objects are listed. the default name audit. BACK-TO-DETAIL Statement This statement is only valid in the AFTER section of a SCREEN or MENU.0 are invalid.5. For further details refer to the ‘TRANSACTION Statement’ section. For further information refer to the Auditing reference manual. The top left corner of the box will be at the co-ordinates specified by the smallest row and smallest column value specified. The bottom right corner of the box will be at the coordinates specified by the largest row and largest column value. This only applies when running on a (dumb) character based terminal. If the same row is specified in both co-ordinates then the result will be a horizontal line.auditing is used. The row and column values of both co-ordinates can be arithmetic expressions. RE-ENTER BEGIN WORK Statement This is equivalent to the TRANSACTION BEGIN statement.col TO @row. that area includes a full character cell position to the bottom right of the 53 . Execution will branch back to either the mode selection of the SCREEN or the option selection of the MENU.col] [DOUBLE] [NO-CROSS] [TITLE IS expression] [SUNKEN] [COLOUR [IS] colour [ON colour]] [ABSOLUTE-COORDINATES] @row. When running on a graphics display device this is ignored as all windows contain borders. top/left) is @1. Note: The co-ordinate for the origin of the screen (that is. Syntax See Also BACK-TO-DETAIL EXIT.2 Row/column values less that 1. Decimal places are supported within the co-ordinates.0.col TO @row. If the same column is specified in both co-ordinates then the result will be a vertical line. This can be used to stop accidental exiting of the routine. the co-ordinate addressing is still based on a character grid. Whilst decimal places are supported. when an area of the screen is addressed. Syntax Clauses BOX [@row. Unless other specified. BREAK. BOX Statement Display a box or horizontal/vertical line on the screen. For example: @10. If no co-ordinates are specified for the box then the box will take the co-ordinates of the current screen (or window). CONTINUE.1 not @0.19.col These are the co-ordinates of two opposite corners of the box. DOUBLE Draw the box with double line drawing characters if available.bmp" @10.4999.0 to @10.10. This clause is obsolete and only applies to character based terminals.10.999.1 TO @23. SUNKEN Boxes with this attribute are drawn with a 3D sunken border.30. 54 .5.1 TO @10.0. DISPLAY ws-text @10.31.20.0 to @23.999.10.20 The above example occupies an area of the screen from @10. For example: BOX @5. If there are no double line characters defined for the terminal type in use then single line characters will be used instead.0.80 The above example refers to an area from @1. DISPLAY BITMAP "abcd.4999.10 to @14.5 to @11. For example: DISPLAY ws-text @10.9999.999.end co-ordinate. NO-CROSS This is used when drawing lines so that the ends form a ‘T’ rather than cross if they intersect with another line/box. the title will be displayed left justified on the top line of the box.999. regardless of whether the title is blank.10 PIC X(20) The above example occupies an area of the screen from @10.40 TITLE IS "Details" Any BOX statement that includes a TITLE clause will be processed as a group box in terms of colour and borders.10 TO @14.80.5.5 PIC X(20) The above example occupies an area of the screen from @10. TITLE If a title is specified for a box.9999 WINDOW @1. This clause is obsolete and only applies to character based terminals.1. See Also DISPLAY BOX-CHAR Statement This statement is obsolete.10 TO @14.10 to @14. if specified. 55 . If a colour is specified for a box with the TITLE clause.70 COLOUR IS BLACK ON WHITE If the SUNKEN clause is also specified then the foreground colour is ignored. REPEAT. ABSOLUTECOORDINATES The box will be drawn at the specified co-ordinates. but the box will be filled with the specified background colour when a background colour has been specified.20 only. Control is passed to the first statement following the end of the loop broken out of. FOR. The foreground colour is the colour of the box border. That is. Normally the co-ordinates at which the box is drawn are offset by half a standard character. and the WHILE. SELECT and EXTRACT loops. For sunken boxes the foreground colour is ignored. For example: COLOUR IS RED ON 0 The standard PRONTO-Xi colours are supported. The colours can be specified as an expression (and hence can be varied at runtime). The background colour is the box ‘fill’ colour. Either the foreground or the foreground and background colours can be specified.10 TO @15. The statement is only valid in the DETAIL command groups of a MENU or SCREEN.bmp" @10. For example: DISPLAY BITMAP "abcd. For example: BOX @10. BREAK Statement This statement is used for loop control.COLOUR or COLOR For example: COLOUR IS RED ON BLACK COLOUR IS BLUE When ‘0’ or no colour is specified the user’s default colours will be used. the colour will only apply to the specified text and not for the box itself. That is.20 ABSOLUTE-COORDINATES The above example occupies an area of the screen from @10. This clause ensures the co-ordinates specified are not offset by the half character. This affects the interpretation of the TO co-ordinate. the box is drawn in the middle of the character cells rather than on the outer edge. The area specified does not include any part of the screen below or to the right of the TO co-ordinate. It is used to break out of the current loop. it does not allow for the additional character position. Arrays are supported. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the operation was successful. If the initial routine of the child program contains the RETURNING clause. It can be any valid alphanumeric expression. If there is an AFTER section for the SCREEN then control will pass to this. BATCH Submit this command to queue zero of the PRONTO-Xi batch queue. Refer to the ‘COMMAND Statement’ for how to execute non 4GL programs. Only alphanumeric parameters can be passed. RETURNING The RETURNING clause allows the receipt of return values from child 4GL programs. The operations table (the compiled form of the . A runtime error will result if too few return values are passed back to the calling program. 56 . Note: The ELSE section of an ON ERROR is only performed if there is no error. ON ERROR Perform these statements if the command specified could not be executed. PARAMETERS List of parameters to pass to the program.When used in the DETAIL section of a SCREEN. EXIT CALL Statement Execute the specified 4GL program (. CONTINUE-ENTRY. Syntax Clauses CALL program-name [PARAMETER[S] [IS|ARE] alpha-expression . otherwise the screen will exit. then DETAIL section loop is terminated. Arrays are supported.spl). Control does not pass back to mode selection. Syntax See Also BREAK CONTINUE. The RETURNING clause in the CALL statement does not need to specify fields for all return values. then the contents of these fields will be passed back to the fields specified in the CALL statement...spl file for the program) must be present on the system. HOME Execute the command with this home directory. The program will not wait for the command to be executed.] [MAX-PARAMETERS [ARE] numeric-expression] [RETURNING field-list] [HOME [IS] alpha-expression] [BATCH] [LEAVE-FILES-OPEN] [EXTERNAL] [BACKGROUND] [ON ERROR procedural-statements [ELSE procedural-statements] END-ON] program-name This is the name of the 4GL program to execute. If a full path name is not specified then the program will be searched for in the directories listed by the PROPATH environment. for example memory and process slots. This statement is only valid within the DETAIL section of a FORM-ENTRY screen. however. The calling program will return immediately and will not wait for the child to complete. If the initial routine of the child program contains the PARAMETERS clause. QUERY. This is different from the LEAVE-FILES-OPEN clause. This clause has no effect on non-Windows based systems. The child program will run independently of the calling program. COMMAND. DO. The PARAMETERS clause of the CALL/QUERY/COMMAND statements allows numeric values to be specified. then parameter values passed will be automatically moved into these fields (with the appropriate data conversions performed where necessary). The PARAMETERS clause does not need to define all expected parameters. This also means that record locks will be maintained. Parameters for external programs are still passed in alphanumeric format. EXIT-STATUS() function CHECK-BOX Statement This statement allows the entry/display of a logical true/false (on/off) value via a check box. as well as possibly slowing down the load time of the child program. Note: Any records that are locked by the calling program will not be able to be locked by the child program. See Also SPL. The RETURNING clause cannot be used as this relies on the calling program waiting for the child program to complete.LEAVE-FILESOPEN Specifies that the files that are currently open in the calling program will not be closed when the child program is invoked. BACKGROUND Flags that the child program should be detached from the calling program and run in the background on graphical systems (for example. as all files will be closed beforehand. EXTERNAL Invokes a new 4GL interpreter to run the child program. regardless of the number of parameters specified.col [VALUES true-value false-value] TITLE title-expression COLOUR colour-name [RIGHT-COORDINATE] [DEFAULT [IS] value] [READ-ONLY] [WHEN expression] [BEFORE-CHECK-BOX 57 . WAIT Wait for child. This is the default option. A runtime error will result if too few parameters are passed to the child program. numeric values will automatically be converted into their preferred alphanumeric format when passed. MAXPARAMETERS Allows an expression to be specified that evaluates to the maximum number of parameters to be passed. This may impose a greater overhead on system resources. This is accomplished by invoking a new 4GL interpreter to run the child program. Notes NO-WAIT Same as BACKGROUND. rather than loading the child program into the current interpreter. Syntax CHECK-BOX field-name @row. Windows and X-Windows). The EXIT-STATUS function will only indicate the success of the command and not the actual exit status of the child program. For further information on FORM-ENTRY screens refer to the ‘SCREEN Declaration’ section. COLOUR or COLOR Changes the colour of the title for the check box. Whenever the value of a field changes this section will be invoked. the check box will be greyed out on the screen. When specified for a RADIO-BUTTON or CHECK-BOX. thus allowing a different text colour to be specified for each check box. If no default value is specified. Any validations will always be performed prior to the ON CHANGE section. Syntax Clauses CLEAR CLEAR CLEAR CLEAR CLEAR CLEAR ROW[S] row-1 [TO row-2] @row. then the false value will be assumed. CLEAR Statement Clear all or part of the screen. RIGHTCOORDINATE The specified coordinates are for the check box to be positioned on the right side of the check box title. For the [Correct] and [Show] modes. or the default value does not match one of the true/false values. Notes If a WHEN condition is specified and is false. 58 . then the false value will be used as the default in [Entry] mode. Check boxes are not currently valid in data grids. Should any validations fail.procedural-statements END-BEFORE-CHECK-BOX] [VALIDATIONS procedural-statements END-VALIDATIONS] [ON CHANGE default-value END-ON] [END-CHECK-BOX] Clauses DEFAULT The DEFAULT clause is used to populate the default value for the field when processed in [Entry] mode. This clause is specified against a specific TITLE for a check box. then the ON CHANGE section will not be invoked. The RE-ENTER Statement and REFRESH Statement are valid for CHECK-BOX fields.col DATA DATA|PROMPT @row.col ABSOLUTE-COORDINATES ROWS Specifies a row range to clear rather than the entire screen. They are not valid in review screens.col TO @row. The format for this clause is the same as for an ACCEPT. ON CHANGE This section is only available if the ACCEPT. This section will be automatically invoked at the beginning of [Entry] mode when the initial value of the fields are set to their default values. If no row range is specified the entire screen (or window) is cleared.col TO @row. This occurs regardless of the previous value of the fields. this section will be invoked immediately when the user changes the value of the radio button or check box. if the value of the field does not match one of the true/false values. RADIO-BUTTON and CHECK-BOX statements are within a FORM-ENTRY screen. 1. ABSOLUTECOORDINATES This affects the interpretation of the TO co-ordinate.31. the co-ordinate addressing is still based on a character grid.0.30. top/left) is @1. See Also DISPLAY.5 PIC X(20) The above example occupies an area of the screen from @10.80 The above example refers to an area from @1. That is.999.1 not @0.20.col Specifies two corner co-ordinates for an area of the screen to clear. Both row and column values can be arithmetic expressions. clear a boxed area of the screen.0.5. DATA PROMPT If the DATA or PROMPT clauses are used in conjunction with a set of coordinates then this specifies that the cleared area should be considered as a field of either type DATA or PROMPT (see the DISPLAY Statement).20 The above example occupies an area of the screen from @10. Decimal places are supported within the co-ordinates.999. The area specified does not include any part of the screen below or to the right of the TO co-ordinate. DISPLAY BITMAP "abcd.0 to @23. that area includes a full character cell position to the bottom right of the end co-ordinate.10. Note: The co-ordinate for the origin of the screen (that is.999.10. That is. clear the contents of all data areas taken up by any ACCEPT or DISPLAY statements in the DETAIL section.5 to @11. For example: DISPLAY ws-text @10.999.10 to @[email protected] TO @14. REFRESH CLOSE Statement Close the physical file associated with an object.10 TO @14. Unless other specified. Whilst decimal places are supported.9999.bmp" @10.col TO @row.20 only.80.10. For example: DISPLAY BITMAP "abcd.4999. DATA Clear only the data parts of the current screen. when an area of the screen is addressed. DISPLAY ws-text @10.10 PIC X(20) The above example occupies an area of the screen from @10. That is. if specified.10 to @14. For example: @10.0. Field borders and headings would not be cleared using this clause.2 Row/column values less that 1. it does not allow for the additional character position.5.19.20 ABSOLUTE-COORDINATES The above example occupies an area of the screen from @10.9999 WINDOW @1.1 TO @23.0 are invalid.bmp" @10. 59 .0 to @10.4999. UPDATE. GET. SERIAL COMMAND Statement Execute the specified operating system command (program). duplicate records) when the index was being generated. Syntax COMMAND program-name [PARAMETER[S] [IS|ARE] alpha-expression . ALL Close all open files. the database was not up).. OPEN. LOCAL This clause is used with the ALL clause. In UNIX a shell script can be invoked as long as execute permission is allowed. ON ERROR Procedural statements to perform if the CLOSE fails. open an Excel spreadsheet or a Word document. See Also OBJECT. UNLOCK. A close can also fail if the object was opened with the INDEX-ON-CLOSE clause. that is: CLOSE ALL RECONNECT Close the existing database connection and attempt to reconnect to the database. For example. This is not necessary if the object was opened with the TEMPORARY clause. and an error occurred (for example. A CLOSE will not cause an error if the file was not open. the file is automatically re-opened (in the same mode and with the same physical file name) if the object is referenced again. that is: CLOSE ALL LOCAL Specify this clause to only affect files in the current operations table. A close will fail if the REMOVE clause was used and the file cannot be removed.] [HOME [IS] alpha-expression] [NO-REFRESH] [NO-XTERM] [MAX-PARAMETERS] [BATCH] [BACKGROUND|NO-WAIT] [WAIT] [EXTERNAL] [ON ERROR] procedural-statements 60 . DELETE. TEMPORARY files will be automatically removed when the program exits. This is intended for use in situations where the database connection may have been lost or if the initial connection to the database failed (for example. This clause can be used to execute/open a Windows based document using standard Windows functionality. This is any executable program on the system. POSITION. EXTRACT. Syntax CLOSE object-name [AND REMOVE] [ON ERROR procedural-statements [ELSE procedural-statements] END-ON] CLOSE ALL [LOCAL] CLOSE ALL [RECONNECT] Clauses AND REMOVE Remove the physical file associated with the object from the file system after it has been closed.Note: Even though it has been closed. RECONNECT This clause is used with the ALL clause.. INSERT. The calling program will return immediately. PARAMETERS List of parameters to pass to the program. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the operation was successful. NO-XTERM Stops the COMMAND statement from calling up an xterm session to run the child task when invoked on an X terminal. The program will not wait for the command to be executed. Windows and X-Windows). This clause has no effect on non-Windows based systems. Arrays are supported. This is the default.[ELSE procedural-statements] END-ON] Clauses program-name This is the name of the program to execute. This clause is obsolete as it applies to character based terminals only. This should only be used when there is no possibility of the child program writing to the screen. MAXPARAMETERS Allows a numeric expression to be specified which evaluates to the maximum number of parameters to be passed. NO-REFRESH Stops the COMMAND statement from refreshing the screen when control is passed back to the calling program. as subsequent screen output from the calling program may be incorrectly positioned. Note: The ELSE section of an ON ERROR is only performed if there is no error. This clause only has an effect when running on the X-Windows version of PRONTO-Xi. 61 . BATCH Submit this command to queue zero of the PRONTO-Xi batch queue. This should only be used when the child task being invoked is an X-Windows program. although this may not be possible when invoking Windows documents. It can be any valid alphanumeric expression. ON ERROR Perform these statements if the command specified could not be executed. and not the actual exit status of the child program. Only alphanumeric parameters can be passed. or NO-WAIT The EXIT-STATUS function will only indicate the success of the command. BACKGROUND Flags that the child program should be detached from the calling program and run in the background on graphical systems (for example. HOME Execute the command with this home directory. regardless of the number of parameters specified. The child program will run independently of the calling program. and will not wait for the child to complete. WAIT Wait for child program to finish before continuing. record removal) will not be performed. For further details refer to the ‘TRANSACTION Statement’ section. CONFIRM Statement Get confirmation before continuing on. The user must be running PROClient on their workstation when using a UNIX based server.col] [AUTO] [WHEN condition] [PROMPT [IS] alpha-expression] [NO-PROMPT] [DEFAULT [IS] YES|NO] [NO-WINDOW|WINDOW] [BEFORE procedural-statements] [CONFIRMED procedural-statements] [NOT-CONFIRMED procedural-statements] [AFTER procedural-statements] END-CONFIRM 62 . Parameters are still passed in alphanumeric format. Only one CONFIRM statement can be present within any SCREEN/PROCEDURE/MENU. WHILE. Excel must be installed on the workstation. numeric values will automatically be converted into alphanumeric format when passed. DO COMMIT WORK Statement This is equivalent to the TRANSACTION COMMIT statement. REPEAT loop or IF statement). It should be the last statement when used in the DETAIL section of a SCREEN or MENU. the required software for that document type must be installed on the workstation. ws-filename END-ON Notes The PARAMETERS clause of the CALL/QUERY/COMMAND statements allows numeric values to be specified. Syntax CONFIRM [@row. For example: IF OPERATING-SYSTEM() != "WINDOWS" COMMAND 'send2proterm' PARAMETERS '-r' ws-unixfilename ws-filename ON ERROR MESSAGE "a c:\tmp must exist" END-ON ENDIF COMMAND ws-filename EXTERNAL NO-WAIT ON ERROR MESSAGE "Could not open".EXTERNAL Run on the local machine (workstation). If confirmation is not given then the Escape flag is set (equivalent to backing out at an ACCEPT) and the action specified (for example. CONFIRM cannot be included in conditional code (within a FOR. however. Note: To open a Windows-based document. This clause is ignored when the application is run on a Microsoft Windows based system (as you are already running on the workstation). For example. See Also SPL. to open an Excel spreadsheet. QUERY. Clauses @row,col Confirmation will be requested via a popup input field at the specified co-ordinates. The row and column values can be arithmetic expressions. Decimal places are supported within the co-ordinates. For example: @10.5,19.2 Row/column values less that 1.0 are invalid. Note: The co-ordinate for the origin of the screen (that is, top/left) is @1,1 not @0,0. Whilst decimal places are supported, the co-ordinate addressing is still based on a character grid. Unless other specified, when an area of the screen is addressed, that area includes a full character cell position to the bottom right of the end co-ordinate. For example: DISPLAY ws-text @10,10 PIC X(20) The above example occupies an area of the screen from @10.0,10.0 to @10.999,30.999. DISPLAY ws-text @10.5,10.5 PIC X(20) The above example occupies an area of the screen from @10.5,10.5 to @11.4999,31.4999. DISPLAY BITMAP "abcd.bmp" @10,10 TO @14,20 The above example occupies an area of the screen from @10,10 to @14.9999,20.9999 WINDOW @1,1 TO @23,80 The above example refers to an area from @1.0,1.0 to @23.999,80.999. PROMPT Use this prompt rather than the default. NO-PROMPT This clause suppresses any prompt message to be printed when asking for confirmation. A three character window will be created to accept the response. The input character is the middle character in the window. A coordinate if specified indicates the position of the input character, rather than the start of the window, as is normally the case. Note: this clause is obsolete and should not be used. DEFAULT Use this response if no response is entered. If this clause is not present then entry of a response is mandatory. AUTO Automatically give confirmation without asking. WHEN Only ask for confirmation when the condition specified is true. When not true, confirmation will be given automatically. NO-WINDOW Do not display a menu based confirmation window. Instead, request confirmation via a popup input field. WINDOW Request confirmation via a menu based confirmation window. This is the default. BEFORE Group of commands to be performed before confirmation is required. CONFIRMED Commands to perform if confirmation is given. Any automatic I/O operation for a screen mode (for example, the [Correct] mode) will have already been performed (and succeeded). 63 NOTCONFIRMED Commands to perform if confirmation is not given. AFTER Commands to perform before the CONFIRM statement finishes, but after any CONFIRMED or NOT-CONFIRMED sections are processed. Commands placed here will also be performed when backing out of a screen or when the automatic I/O operation for a screen mode (for example, the [Correct] mode) fails. CONTINUE Statement This statement is used for loop control. It ignores the rest of the code in the current loop and continues execution at the next iteration. This statement is valid only in the DETAIL command groups of a MENU or a SCREEN, or within the WHILE, FOR, REPEAT, SELECT, and EXTRACT loops. When used in the DETAIL section of a SCREEN, control is passed back to the mode selection. Syntax See Also CONTINUE BREAK, EXIT, CONTINUE-ENTRY CONTINUE-ENTRY Statement When a screen is in [Entry] mode and the CONTINUE statement is executed, control is passed back to the mode selection rather than continuing at the next iteration of the [Entry] mode. The CONTINUE-ENTRY statement will stop processing the DETAIL section at the point in which it is encountered and continue with the next iteration of the [Entry] mode (that is, from the start of the DETAIL section). This statement is only valid in the DETAIL section of a SCREEN. It has absolutely no effect unless the screen is processing an [Entry] type mode. Syntax See Also CONTINUE-ENTRY BREAK, CONTINUE, EXIT DELETE Statement Delete the current record for the specified object. Syntax Clauses DELETE object-name [NO-WARNING] [ON ERROR [error-number, ...] procedural-statements [ELSE procedural-statements] END-ON] NO-WARNING Do not generate compiler warnings regarding the object potentially not being locked. ON ERROR [error-numbers] Procedural statements to perform if the DELETE fails. If the ELSE clause is used then the procedural statements following the ELSE will be performed if the DELETE succeeds. The ON ERROR clause of any I/O operation can have a list of error numbers specified (directly after the ON ERROR). The ON ERROR section will only be performed if the error is one of those listed. If the error is not in the list then the program will abort. 64 Notes You must have currency on the record that you are deleting. The record should be locked prior to the delete operation, as the delete will fail if it is locked by another user. A runtime error can occur if an attempt is made to delete a record that is not locked. See Also OBJECT, OPEN, CLOSE, GET, INSERT, UPDATE, POSITION, UNLOCK, EXTRACT, SERIAL, INITIALISE, SAVE, RESTORE DISABLE-ALL-TRIGGERS Statement Disable all data trigger processing within the current program and any attached component libraries. This applies to both standard/core and user-defined data triggers. This statement is specifically intended for use by data transformation and upgrade programs where all trigger processing within the program is not valid.  Warning: This statement should be used with extreme caution. There is no ability to re-enable trigger processing within the program once this statement has been executed. Syntax DISABLE-ALL-TRIGGERS Notes The NO-TRIGGER clause on the OPEN Statement should be used to disable individual triggers. See Also OPEN DISPLAY Statement Displays the result of an expression on the screen. Syntax DISPLAY expression @row,col [PIC [IS] picture] [BLANK-WHEN-ZERO] [BLANK-WHEN-DECIMALS-ZERO] [BOLD] [DIM] [FLASHING] [INVERSE] [ITALIC] [UNDERLINED] [BELL] [FOREGROUND] [BACKGROUND] [DATA] [PROMPT] [COLOUR [IS] colour [ON colour]] [SCALE [IS] expression] [FIXED-WIDTH-FONT] [LEFT|CENTRE|RIGHT|CENTRE-COORD|RIGHT-COORD] [TITLE expression] DISPLAY BITMAP expression @row,col [TO @row,col] NO-WAIT Clauses expression A valid numeric or string expression. @row,col Screen co-ordinates at which to display the expression. The row and column values can be arithmetic expressions. Decimal places are supported within the co-ordinates. For example: @10.5,19.2 Row/column values less that 1.0 are invalid. Note: The co-ordinate for the origin of the screen (that is, top/left) is @1,1 not @0,0. 65 Whilst decimal places are supported, the co-ordinate addressing is still based on a character grid. Unless other specified, when an area of the screen is addressed, that area includes a full character cell position to the bottom right of the end co-ordinate. For example: DISPLAY ws-text @10,10 PIC X(20) The above example occupies an area of the screen from @10.0,10.0 to @10.999,30.999. DISPLAY ws-text @10.5,10.5 PIC X(20) The above example occupies an area of the screen from @10.5,10.5 to @11.4999,31.4999. DISPLAY BITMAP "abcd.bmp" @10,10 TO @14,20 The above example occupies an area of the screen from @10,10 to @14.9999,20.9999 WINDOW @1,1 TO @23,80 The above example refers to an area from @1.0,1.0 to @23.999,80.999. PICTURE or PIC Display the result of the expression using this format rather than the default format used. A PICTURE on a DISPLAY or ACCEPT will adjust the amount of space used by the field on the screen, but will not limit the amount of characters being displayed (or entered). The amount of characters being displayed (or entered) is based on the definition of the field. For example, it is possible to display a 30 character field when a PIC X(20) is specified. The amount of characters displayed will depend upon their size. The picture string can be specified as an alphanumeric expression that is evaluated at runtime. See below for a description of valid PICTURE string characters. BLANK-WHEN-ZERO BLANK-DECIMALSWHEN-ZERO The BLANK-WHEN-ZERO clause generates a PICTURE that will display blanks if the value is zero. The BLANK-DECIMALS-WHEN-ZERO clause generates a PICTURE that will display blanks where the decimal places would normally be displayed, if the decimal places are zero. These clauses cannot be used in conjunction with a PICTURE clause. BOLD ITALIC INVERSE UNDERLINED DIM FLASHING BELL BOLD, ITALIC and UNDERLINE will apply the appropriate windows font. FLASHING is obsolete, but if used will apply user-defined colours. FIXED-WIDTH-FONT This clause causes the font used to be the fixed width font defined, rather than the variable (proportional) width default. DATA DATA specifies that the expression when displayed will be enclosed within a data border. PROMPT specifies that no data border should be used. PROMPT DIM is obsolete, but if used is the equivalent of specifying BACKGROUND. BELL will cause a beep to be sounded. PROMPT is the default for a DISPLAY in the BEFORE section of a SCREEN or MENU. DATA is the default in all 66 The aspect ration of the bitmap will be preserved if any scaling is performed. SCALE [IS] expression For example: DISPLAY "Hello world" @1. FOREGROUND and BACKGROUND are shown with different colour settings.other circumstances. FOREGROUND indicates that the expression is not a title (that is.1 SCALE IS 300 BITMAP Allows a bitmap image to be displayed on the screen. PRONTO-Xi will attempt to select a bold (thick) version of the font with the required scaling. All standard Microsoft supported bitmap formats can be used (for example. FOREGROUND BACKGROUND Specifies whether this DISPLAY should be considered as a title to a data field. 67 . etc. The colours can be specified as an expression (and hence can be varied at runtime). the bitmap will be scaled down (if needed) to fit within the specified area. BACKGROUND is the default for a DISPLAY in the BEFORE section of a SCREEN or MENU.). individual cells can have separate colours specified (by using an expression for the colours). SCALE Allows the scaling factor of the font used within the DISPLAY statement to be altered. A scale of 100 (that is. When this clause is used in a DATA-GRID. If the BOLD attribute is also specified in the DISPLAY statement. COLOUR or COLOR For example: COLOUR IS RED ON BLACK COLOUR IS BLUE When ‘0’ or no colour is specified the user’s default colours will be used. If a TO coordinate is specified. A field type of COLOUR (for example. TYPE IS COLOUR) can be used. If a single co-ordinate is specified. JPEG. Either the foreground or the foreground and background colours can be specified.. this co-ordinate refers to the location of the top left corner of the bitmap. etc. data). BMP. Fields storing colours must be at least PIC 9(5). The bitmap file is considered as data and must be able to be accessed by either PRONTO-Xi on the machine that the application is running on. For example: COLOUR IS RED ON 0 The standard PRONTO-Xi colours are supported. If the bitmap is smaller than the area it will be stretched to fit within the area specified for the bitmap. as the width of individual characters varies within the font. BACKGROUND is used to indicate that the expression is a title to a field. Note: Proportional fonts base their size on their height and not their width. FOREGROUND is the default in all other circumstances. A scale of 50 is half size and 200 is double. or via PROCLIENT (UNIX versions only).. The syntax of the clause is: DISPLAY . 100 percent) is normal. 20 ABSOLUTE-COORDINATES The above example occupies an area of the screen from @10. Review screens and data-grids can set the title for the column using the title clause of the DISPLAY statement (removing the need for separate title displays in the BEFORE section). The RIGHT-COORD indicates that the coordinate represents the far right position of the field (and also right justifies the text within the field). That is. The syntax of the DISPLAY BITMAP statement is: DISPLAY BITMAP alpha-expression @row. The LEFT clause causes text to be left justified (this is generally the default).10 to @14. 68 .col] For example: DISPLAY BITMAP "c:\bitmaps\bitmap.bmp" @10.10 The BACKGROUND clause can be used to specify that the background bitmaps can be overlaid by text and other fields within a window.jpg" @10. otherwise this is not done until user input is requested. the bitmap will be stretched/shrunk both vertically and horizontally to fully fit the specified area. That is.10 NO-WAIT LEFT CENTRE RIGHT CENTRE-COORD RIGHT-COORD TITLE The CENTRE clause causes text to be centred within the field rather than left justified. no TO co-ordinate is given to specify an area. The NO-WAIT clause may be specified to force a bitmap to be sent immediately to the client.col [TO @row.20 only. it does not allow for the additional character position. The area specified does not include any part of the screen below or to the right of the TO co-ordinate.) For example: DISPLAY BITMAP "/pronto/bitmaps/test. if specified.10 TO @14. A negative value shown with an unsigned picture will also be shown as a set of question marks. Notes Overflows of displayed fields: A field/expression DISPLAYed or PRINTed that is too large for its default (or specified) PICTURE will be shown as a set of question marks (see later for an exception).bmp" @10. The CENTRE-COORD indicates that the co-ordinate represents the centre of the field (and also centres the text within the field). The ABSOLUTE-COORDINATES clause affects the interpretation of the TO co-ordinate. Note: If a variable expression is used then the value must be set in the BEFORE section or prior to the SCREEN being invoked. That is.unless the NO-ASPECT-RATIO clause is specified. The RIGHT clause causes text to be right justified within the field rather than left justified. (This only impacts PRONTO-Xi Thin Client implementations. The NO-ASPECT-RATIO clause can be used to indicate the aspect ratio of the bitmap is not to be maintained if the bitmap is stretched or shrunk. For example: DISPLAY BITMAP "abcd. if it is not cached there. 23E+9) if this fits within the allocated size. If used with the ‘Z’. YY Year shown as a two digit number (year within century). MMM Month shown as the first three characters of its name. the box or bitmap will show through). it will not be shown for leading zeros. however. This will result in a loss of precision (that is. 69 . but the whole (integer) portion of the number can be displayed in the space provided by ignoring the decimal places. rather than the value being shown as all question marks ‘?’. DD Day shown as a two digit number. MM Minute as a two digit value.If the value to be displayed is too large for the PICTURE specified. HH Hour as a two digit value (24 hour clock by default). . . the REVERSE or the COLOUR statement). except leading zeros will be suppressed. If multiple leading minus signs are specified then the minus sign will “float” over leading zeros to be positioned before the first non-zero digit. A DISPLAY statement that is positioned over a BOX or a BACKGROUND BITMAP will be transparent (that is. otherwise it represents an integer digit. YYYY Year shown as a four digit number (including the century). Numeric fields whose size when displayed is larger than the allowed number of characters will be displayed in exponent format (for example. then the value will be displayed without decimal places. % Inserts a percent sign. This does not apply to displays that have a background colour specified (for example. This means that the value displayed may be out of alignment with other values displayed. It is not recommended to use these as these symbols may be meaningless in some countries. The brackets must surround the other picture string characters. Numeric Picture Characters Date Picture Characters Time Picture Characters 9 Specifies a single numeric digit. MM Month shown as a two digit number. rounding). 1. Z Similar to ‘9’. SS Second as a two digit value. . Insert this character for punctuation.(Minus sign) Indicates the position of the sign character when a value is negative. (Comma) This is used for punctuation within a number. (Dot) Specifies the location of the decimal point. DR or CR Shows “DR” or “CR” if the value is negative. B or space . () Shows the value as enclosed in brackets when the value is negative. $ Specifies that the currency sign should be shown. T Specifies the location of the decimal point. it will give an indication of the true value. it does mean that the value is still visible.(hyphen) / (slash) . If this character occurs after the decimal point (if present) then it indicates a decimal digit. however. (comma) Inserts a blank (space) for punctuation. ‘$’ or ‘-‘ pic characters. This also signifies that decimal places (including the decimal point) are to be shown as blank if zero. If multiple leading currency signs are specified then the currency sign will “float” over leading zeros to be positioned before the first non-zero digit. Alpha Picture Character X Specifies a single alphanumeric character. MESSAGE.] [RETURNING fieldnames] [NEXT routine] screen-mode A standard screen mode (for example. If a screen is called with only one mode. . SAME Perform the screen using the same screen modes as the current screen. PROCEDURE. A DATE-TIME field that is directly used in this way will assume that it is based on local time (with no GMT timezone offset).AM or PM Show AM if hour is less than 12 otherwise show PM. the screen will automatically be placed in that mode as usual. Picture Character Repetition Any single picture character that can repeat (for example. ENTRY) or a user specified screen mode declared in a MODE statement. 999999) can be specified in the following format: picture-char(repetition) For example: $(10)9. B or space Inserts a blank (space) for punctuation.. ACCEPT and PRINT statements) is ‘DD-MMM-YYYY HH:MM:SS’. For example. Syntax Clauses DO screen-name | procedure-name | api-name | menu-name [screen-mode1 [screen-mode2 . SHOW mode can be specified in mode list with other modes. SUB-SCREEN The screen to perform is to be considered as a sub-screen.. These modes have no effect if a menu or procedure is being called.99- Data Type DATE-TIME The default PICTURE format used (for the DISPLAY.]] [SAME] [ONCE] [SUB-SCREEN] [INITIAL-MODE [IS] screen-mode] [PARAMETERS [ARE] value. REFRESH DO Statement Perform the specified SCREEN. : (colon) Used for punctuation. BOX.. The standard DATE and TIME PICTURE characters can be used in combination for the DATE-TIME field. If the screen performed is backed out of then it will be considered equivalent to backing out of the current screen. API or MENU defined within the current program. 70 . See Also ACCEPT.99is equivalent to $$$$$$$$$$9.. only allow for entry once rather than multiple times (as is the default). CLEAR. If a DATE-TIME field is stored in GMT then it should not be used directly in a DISPLAY/ACCEPT/PRINT. ABORT. ONCE Only perform the screen for one iteration of the DETAIL section. Any modes specified here will take precedence over the modes defined for the screen being called. Syntax See Also END-STATEMENT-GROUP STATEMENT-GROUP ENQUIRY Statement Refer to the ‘QUERY Statement’. RETURNING Specify a field or fields that are to receive the return values from the routine called. PARAMETERS Specify fields. then the exit status value will be returned to the calling program. That is. Exit status return values should be 0 or greater to avoid conflict with default runtime generated exit status values. A routine that exits normally (without the EXIT statement) sets an exit status of 0. The NEXT is specified immediately after the DO and before the name of the routine. Syntax See Also END-OPTION OPTION END-STATEMENT-GROUP Statement This statement specifies the end of a statement associated with the STATEMENT-GROUP statement.255. PROCEDURE. This can be specified as a numeric expression.See Also INITIAL-MODE Place the screen into this mode initially. NEXT Specify a routine. In this circumstance. Syntax Clauses EXIT [exit-status] exit-status Exit status value to be returned. The number and data types of the fields passed must match that of the parameter list of the routine being called. values or expressions that are passed to the routine as parameters (arrays supported). DO NEXT routine SCREEN. MODE. When the screen has been processed in this mode once. An exit status value of -1 is set automatically if the EXIT statement does not specify a value. If the EXIT statement is used to exit the initial (main) routine of the program. Arrays are supported. CALL. This will call the next component library level of an EXPORT routine. QUERY END-OPTION Statement This statement specifies the end of a statement associated with the OPTION Statement. the list of other available modes will be displayed for selection. MENU. The initial mode specified need not be contained in the list of other modes to perform. Screens and menus will loop until they are escaped out of (by the user) or until an EXIT statement is encountered. EXIT Statement Forcibly exit the current SCREEN/PROCEDURE/API/MENU. the exit status value should be in the range 0 . 71 . API. EXIT. CONTINUE. Multiple DETAIL procedures are not allowed. exclude records that do not meet this condition. If no direction is specified a default of NEXT is assumed. If no ON INDEX clause is specified the object will be accessed on index 1. NEXT or PREVIOUS clause. position at the start of the file and read sequentially through. [AFTER [field-list] procedural-statements] . 72 . . . . KEY Specifies a starting position for the extract.The EXIT-STATUS function can be used to query the exit status value of the last routine called or program executed. DO. For further information refer to the ‘GET Statement’ section. If not specified. . The loop terminates when the object specified reaches the end of file/list.. See Also CALL. LOCK Lock records in this object as they are extracted. or by listing every field (in order) which makes up the key to the required index (see Notes below). Note: The PREVIOUS clause is not supported on all database systems and should be avoided. Syntax Clauses EXTRACT object-name [ALL] [NEXT|PREVIOUS [SAME|DIFFERENT [field-list]] [LOCK] [ON INDEX index] [KEY [IS] expression . FINISH WHEN Force the EXTRACT loop to finish when the condition is met. ON INDEX Force the EXTRACT to read the object using this index. DETAIL Specifies procedural code that will be performed for every extracted record. The verbs WHEN and WHERE are equivalent. BREAK EXTRACT Statement The EXTRACT statement allows conditional looping while sequentially reading records from a single object. the file will automatically be positioned at the start (or the end if reading backwards). That is. COMMAND. NEXT/ PREVIOUS Specifies the direction and method of reading records. that is.. END-EXTRACT ALL Read all records for the specified object. This is the default if there is no KEY. 1).] [WHERE condition] [FINISH WHEN condition] [DETAIL procedural-statements] [BEFORE [field-list] procedural-statements] . WHERE Extract records only when the condition specified is satisfied. index can be specified by the index number (for example. then repeatedly performs the procedural statements until field-name reaches (exceeds) the TO value.BEFORE [fieldlist] Specifies procedural code that will be performed BEFORE the DETAIL procedure when one or more of the specified fields changes its value. By default the value is one (1). INSERT. Syntax Clauses Notes FOR field-name = expr [DOWN] TO expr [STEP expr] [DETAIL] procedural-statements END-FOR DETAIL Used only for readability and consistency with other looping constructs. OPEN. using the BREAK statement) then the value of field-name will be its value at the time the loop was terminated. Current field values will be that of the previous record (that is. See Also OBJECT. AFTER [field-list] Specifies procedural code that will be performed AFTER the DETAIL procedure when one or more of the specified fields changes its value. The index used will be the first index found with the specified leading fields. SERIAL. The operation will act as though the real index only contained the leading fields that correspond to the number of key values specified. If a partial field list is used for the ON INDEX clause. GET. It will not be performed if no records are processed. There is no need to do a position as the UPDATE statement will not change the position in the table. otherwise. the key field must be reset back to the old value before continuing the extract. the NEXT SAME will fail. field-name is decremented rather than incremented and the loop terminates when field.name is less than the TO value. When the NEXT SAME. POSITION. for example EXTRACT. Changing a key field within the extract (via an UPDATE statement) and using a NEXT SAME. BREAK. An AFTER section specified without a field list will be performed once at the end of the EXTRACT loop if the EXTRACT loop processes records. It will not be performed if no records are processed. Notes A field list for the ON INDEX only needs to match the leading fields of a valid index. STEP Specifies the increment/decrement value for field-name after every iteration. DOWN The loop normally terminates when field-name is greater than the TO value. FINISH WHEN then WHEN. FINISH WHEN and WHEN clauses are used for an EXTRACT statement the order of the checks is NEXT SAME. Multiple AFTER clauses can be used. A BEFORE section specified without a field list will be performed once at the start of the EXTRACT loop if the EXTRACT loop processes records. the operation will act as though the real index only contained the specified fields. UPDATE. Values do not need to be specified for each of the fields in the index used. UNLOCK. they do not match the current record for the object being EXTRACTed). DELETE. If DOWN is specified. CLOSE. If the FOR loop runs to completion then field-name will not be equal to the TO value. Multiple BEFORE clauses can be used. CONTINUE FOR Statement This sets field-name to the initial value specified. but instead the TO value plus the STEP value. 73 . If the loop is terminated (for example. Current field values will be that of the new record. LAST Read the last record on file for the specified index. BREAK. If the DIFFERENT clause is specified. If no fields are specified then the current key fields will be assumed.. 74 . IF. LOOKUP Read only to determine if the record exists. The values of fields in the record that are not listed will not be altered. SWITCH. 1) or by listing fields (in order) which makes up the key to the required index. KEY Specifies the key values to use for random (key) reads.] procedural-statements [ELSE procedural-statements] END-ON] NEXT/ PREVIOUS Read sequentially the next/previous record for the file. ON INDEX Read the record using this index. FIRST Read the first record on file for the specified index. The ON ERROR clause should be used to determine the existence or non-existence of the record. field-list FROM List of fields to retrieve instead of the entire record. Warning: An UPDATE operation will unlock the record unless the LOCK option is specified with it. Only the values for the fields listed will be set to those of the record read. index can be specified by the index number (for example.. Note: The PREVIOUS clause is not supported on all database systems and should be avoided. If the SAME clause is specified. If no ON INDEX clause is specified then the object will be accessed on index 1.. Refer to the ‘LOCK-METHOD Statement’ for how locked records are handled when encountered. the record accessed cannot have the current value of the specified fields. the record accessed will have the current value of the specified fields. The values specified here are moved into the corresponding key fields (even if the GET fails). Syntax Clauses GET [field-list FROM] object-name [NEXT|PREVIOUS [SAME|DIFFERENT [field-list]] [FIRST|LAST|CURRENT|LOOKUP] [LOCK] [ON INDEX index] [KEY [IS] expression . LOCK Lock the record read. CURRENT Reread the current record.] [ON ERROR [error-number . This option will not affect the currency or any field values of the object.See Also WHILE. CONTINUE GET Statement Get (read) a record from the specified object. If this option is not used then all fields for the record read will be retrieved.. The record will remain locked until it is explicitly unlocked (using the UNLOCK statement) or it is no longer the current record for the object. If a partial field list is used for the ON INDEX clause. Notes Only one of the NEXT. The ON ERROR clause of any I/O operation can have a list of error numbers specified (directly after the ON ERROR). UPDATE. CURRENT and KEY clauses can be specified. The ON ERROR section will only be performed if the error is one of those listed. See Also OBJECT. LOCK-METHOD IF Statement Conditionally perform procedural statements. INSERT. Records in text files (including External and PRN format files) can be read in reverse order by using the PREVIOUS option on the GET statement. LAST.ON ERROR [error-numbers] Specifies procedural statements to perform if the GET fails. SAVE. the record with the highest value for the unspecified key field(s) will be returned. INITIALISE. If none of the above clauses are specified then the GET will read the record with the current key values. this operation is performed using a variation of a binary search. This operation should be used sparingly in circumstances where the number of records to search through to find the last record is large. RESTORE. That is. Values do not need to be specified for each of the fields in the index used. the last record with the specified key values will be returned. Syntax IF logical-expression [THEN] procedural-statements 75 . SERIAL. This means that several (or dozens) of read operations may be required to locate the required record. On RDBMS versions. POSITION. If the ELSE clause is specified then the procedural statements following the ELSE clause will be performed if the GET succeeds. If the KEY IS clause specifies a value for every key field. The verbs END and ENDIF are interchangeable. DELETE. If the error is not in the list then the program will abort with a full error detail screen. The KEY IS clause: If the KEY IS clause does not specify a value for every key field. The ON INDEX clause: A field list if specified only needs to match the leading fields of a valid index. The index used will be the first index found with the specified leading fields. The most common conditions that will cause the GET to fail are end of file and record not found. OPEN. the operation will act as though the real index only contained the specified fields. FIRST. CLOSE. The operation will act as though the real index only contained the leading fields that correspond to the number of specified key values. PREVIOUS. UNLOCK. That is. Note: The ELSE section of an ON ERROR is only performed if there is no error. The KEY IS clause can contain values for all of the key fields of the index used only if the last key field is alphanumeric. The FIRST and LAST clauses for the GET and POSITION statements are also valid for text files. the record with the highest value for the unspecified part of the last key field (the trailing blanks) will be returned. the last record with the specified part of the last key will be returned. EXTRACT. DELETE. DELETE. UPDATE. Note: There is no current record after the INSERT statement. Notes ELSE-IF is one word (that is.. Syntax Clauses INSERT object-name [LOCK] [ON ERROR [error-number . Multiple ELSE-IF clauses can be specified.[ELSE-IF logical-expression procedural-statements] . REPEAT. [ELSE procedural-statements] ENDIF Clauses THEN Optional. See Also INSERT. The key used for the new record is the contents of the key fields on that record. The ON ERROR clause of any I/O operation can have a list of error numbers specified (directly after the ON ERROR).. A GET (by key) needs to be executed to regain currency. SERIAL. SWITCH INITIALISE Statement Initialise (reset) the values of all fields contained in the object to their default null value. ELSE Perform these procedural statements if none of the IF/ELSE-IF conditions are met. Syntax INITIALISE object-name [LEAVING field-name [. . Separating the ELSE and the IF will create a nested IF statement which will require another ENDIF. The insert will fail if the key specified is unique and is already present. This is useful prior to an INSERT operation to ensure that fields that are not meant to contain values are initialised. GET. The fields listed must be contained in the specified object. no spaces). If the ELSE clause is used then the procedural statements following the ELSE will be performed if the INSERT succeeds.] procedural-statements [ELSE procedural-statements] END-ON] ON ERROR [error-numbers] Procedural statements to perform if the INSERT fails.]] Clauses LEAVING Fields that are listed after the LEAVING clause are not initialised. UPDATE. OPEN. If the error is not in the list then the program will abort with a full error detail screen.. CLOSE. See Also FOR. Provided for readability only. ELSE-IF This is a method of combining several IF statements together. The ELSE-IF condition is tested only when the IF condition (and all previous ELSE-IF conditions) are not true. . The ON ERROR section will only be performed if the error is one of those listed. GET INSERT Statement Insert a new record into the object. POSITION. EXTRACT. See Also OBJECT.. field-name . 76 . WHILE. When running interactively. [NO-BELL] PICTURE or PIC Allows the default format to be overridden in which the preceding expression is displayed. See Also GET MESSAGE Statement Displays an informational message on the screen. The operation will fail immediately if it encounters a locked record. When in a batched or API program. This clause stops the bell from sounding. the user will be prompted periodically as to whether they wish to continue retrying. If multiple expressions are specified they will be concatenated and displayed as one message. NO-BELL By default. the terminal’s bell will sound when a message is displayed. Syntax Clauses LOCK-METHOD [IS] [WAIT|NO-WAIT|WAIT-WITH-TIMEOUT] WAIT Wait for the record to become unlocked. See Also EXPORT LOCK-METHOD Statement Specifies how locked records are to be handled when encountered. . This method can be set to force an indefinite wait. Notes The WAIT-WITH-TIMEOUT is the default for interactive applications. “deb/m10shl”). WAIT-WITHTIMEOUT This will continue to retry the operation until the record is no longer locked. The WAIT option is the default for batched/background applications. The full path names should not be specified. NO-WAIT Do not wait for the record to become unlocked. this method does not wait indefinitely and locks will timeout after retrying for 30 seconds.UNLOCK. INITIALISE. This will continue to retry the operation until the record is no longer locked. Syntax LINK component-library-name Notes Multiple LINK statements can be specified and can refer to an already specified component library. 77 . RESTORE LINK Statement The LINK statement is used to attach a component library to a program. The picture can be an expression that is evaluated at runtime. This statement specifies the names of the component libraries containing routines referenced by the program. Component library names are specified in the same manner as standard PRONTO-Xi programs when these are invoked (for example. Syntax Clauses MESSAGE expression [PIC [IS] picture-string] [expression [PIC [IS] expression]] . . SAVE. Note: See below for an example DEFAULT Allows the default button on the message box to be specified. It does not imply a pause.Notes Messages will be displayed in a popup message box window with an [OK] button. Syntax Clauses MESSAGE-BOX alpha-expression [TITLE [IS] alpha-expression] [MESSAGE-BUTTONS numeric-expression] [DEFAULT [IS] numeric-expression] [ICON [IS] numeric-expression] [TAG [IS] numeric-literal] [HELP-CONTEXT help-file-name help-id] [OPTIONAL] [BELL] MESSAGEBUTTONS The allowed buttons are specified by the MESSAGE-BUTTONS clause with a number that is based on the following predefined values: MSG_BOX_OK MSG_BOX_CANCEL MSG_BOX_YES MSG_BOX_NO MSG_BOX_RETRY The following combination values can also be used: MSG_BOX_OK_CANCEL MSG_BOX_YES_NO MSG_BOX_YES_NO_CANCEL. the MESSAGE statement will display a message at the bottom of the screen and continue executing the program. The user will be required to press the [OK] button to acknowledge the message before execution of the program will continue. If the PAUSE statement immediately follows a MESSAGE statement without the NO-BELL clause. 78 . the PAUSE will be ignored (to avoid an additional unwanted user interaction). ABORT MESSAGE-BOX Statement This statement is used to display a configurable multi-line message box. See Also DISPLAY. When running on a “dumb” character based terminal. If a subsequent MESSAGE statement is encountered before the program requires input from the user. A MESSAGE statement with a NO-BELL clause that is immediately followed by the PAUSE statement will also be displayed in a message box/window. Messages with the NO-BELL clause will be displayed on the status line at the bottom of the controlling window frame. TAG The TAG clause is used to uniquely identify the message box within the screen. ICON The icon to use is specified by the ICON clause with a number that is based on the following predefined values: MSG_BOX_STOP MSG_BOX_WARNING MSG_BOX_INFORMATION MSG_BOX_QUESTION Note: MSG_BOX_EXCLAMATION is also defined but is the same as MSG_BOX_WARNING. then the system will display ‘PRESS ENTER’ in the bottom left hand corner and wait for the user to do so before displaying the subsequent message. This ensures that the user sees prior messages. Note: A literal number must be specified for this clause. Expressions are not allowed. ICON MSG_BOX_STOP // Icons: // MSG_BOX_STOP. DISPLAY. MSG_BOX_YES_NO. BELL Notes The BELL clause will cause a beep to be sounded when the message box is displayed. HELPCONTEXT The HELP-CONTEXT clause will cause a Help button to be shown which will invoke context sensitive help." ELSEIF message-status = MSG_BOX_NO MESSAGE "Please check your license is valid. // MSG_BOX_RETRY. MSG_BOX_QUESTION. UNIX/Linux implementations require PRONTO-Xi Thin Client 6. // MSG_BOX_INFORMATION. MSG_BOX_NO. Syntax NEED numeric-expression [LINES] [ON report-name] 79 . Only a single <alpha-expression> can be specified. refer to the PARAM-TEXT() section. This function will return the button code as used in the MESSAGE-BUTTONS clause.4 for the full features of the MESSAGE-BOX statement. // then need to define a tag. MSG_BOX_WARNING. MESSAGE-STATUS(). Note: The TAG clause must be specified to identify the message.7v0. MSG_BOX_CANCEL. // MSG_BOX_YES. The MESSAGE-STATUS() function can be called after the MESSAGE-BOX statement to identify the button that was pressed. If you make it optional. For information on a method of displaying multiple values. ABORT MESSAGE-BOX Statement Example PROCEDURE message-box-example MESSAGE-BOX "Did you know it's Duck Season ?" TITLE "License Information" MESSAGE-BUTTONS MSG_BOX_YES_NO // Button Groups : // MSG_BOX_OK_CANCEL." ENDIF END-PROCEDURE// NEED Statement Force a new report page if the number of lines left in the current page is less than the specified amount. See Also MESSAGE. OPTIONAL The OPTIONAL clause is used to specify that the message box includes a check box option to not receive this message again. // MSG_BOX_EXCLAMATION // BELL Sounds a bell as the message box is displayed // OPTIONAL Adds a check box to ask if the message // is to appear again. // MSG_BOX_YES_NO_CANCEL. DEFAULT MSG_BOX_NO // Individual Buttons: // MSG_BOX_OK. // IF message-status = MSG_BOX_YES MESSAGE "Note: A number of ducks have placed themselves on the Endangered Species List. // You must ensure the tag number's //uniqueness in the program yourself. 80 . CREATE Create the physical file/table for the object if it does not already exist. the file is opened automatically the first time it is referenced using the default file (table) name defined. SKIP. If this is not specified the file will be opened for reading and writing. This only applies if the file was created/truncated as a result of this OPEN. otherwise create it. This clause is not supported on all file types and database implementations. and all indexes created. then this one will be used again if an automatic open is performed.] procedural-statements [ELSE procedural-statements] END-ON] FILE IS file-name Open this physical file rather than the current default file name. READ-ONLY Only allow read access of the file within the program. The initial default file name is specified in the object’s definition. Syntax Clauses OPEN object-name [FILE [IS] file-name] [LOCK] [CREATE] [TRUNCATE] [PERMANENT|TEMPORARY] [PRIVATE] [NO-TRIGGERS] [LOCAL] [READ-ONLY] [INDEX-ON-CLOSE] [ON ERROR [error-number . filename can be any valid alphanumeric expression. If duplicate records are inserted on an index that does not allow them. If the object was previously opened with a different file name. INDEX-ONCLOSE Create all indexes to the table when the object is closed (rather than when the table is created).Clauses ON report-name Indicates that this print operation is only for the specified report. LOCK Open the file for exclusive use. This can improve performance where a large number of records are to be inserted into this table by the program. and the program should take the necessary steps (for example. See Also REPORT. the CLOSE operation will fail (with a duplicate record error). Note: If this statement is not issued for an object. The indexes will not have been successfully created if this occurs.. PRINT. TRUNCATE Reset the physical file/table to zero records if the file exists. PAGE OPEN Statement Open the file associated with an object for use within the program. No access to the inserted records is possible until the object is closed. remove the table and create it again without this clause).. The file name specified in the FILE IS clause becomes the new default file name after the OPEN has been performed. If the FILE IS clause is not used then PERMANENT is assumed. if you specify the FILE IS clause when you OPEN the object. SERIAL 81 . The ON ERROR section will only be performed if the error is one of those listed. The TEMPORARY clause also implies TRUNCATE when opened. For example: OPEN deb-master NO-TRIGGERS LOCAL This option is obsolete and should not be used. PERMANENT TEMPORARY If the TEMPORARY clause is specified in the OPEN for an object then the file for this object will automatically be removed when the program terminates (if the file still exists). CREATE. NO-TRIGGERS This clause is used to disable a trigger for an object.ON ERROR [error-numbers] Procedural statements to perform if the OPEN fails. TRUNCATE and TEMPORARY) indicates that the file created should not allow read/write access by other users. A similar effect can be achieved by prefixing the name of the file with a colon (:) or exclamation mark (!).. GET. a unique temporary file name will be automatically generated. This clause indicates that the file resides on the local machine instead of the server machine. PRIVATE This clause when used in conjunction with any of the file creation clauses (that is. the following file name indicates that the file is located on the local machine: :/tmp/abcd Both these options can be used on non-network versions without error. may need to turn trigger processing off for certain objects. DELETE. UPDATE. Programs that perform data conversion. However. etc. Both these operations will cause the current temporary file to be removed. See Also OBJECT. The ON ERROR clause of any I/O operation can have a list of error numbers specified (directly after the ON ERROR). POSITION. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the OPEN succeeds. If no explicit file name is specified using the FILE clause in the OPEN statement. CLOSE. in which case it will reuse its current temporary file name. the temporary file will be removed at this point (even if the file name passed is the same as the current temporary file). UNLOCK. You can OPEN and CLOSE an object with a temporary status after its initial creation without changing its status or having the file automatically removed. Only the user who created the file will have any access to it. Only a CLOSE with the AND REMOVE clause or an OPEN with the FILE IS clause can remove the temporary status of the object. INSERT. will default to TEMPORARY unless the PERMANENT clause is used. The default/current file name for the object will never be used unless the object is already flagged as temporary. EXTRACT. Notes Any OPEN statement that uses a FILE IS clause to identify the name of the file to create. For example. If the error is not in the list then the program will abort with a full error detail screen. up to the next OPTION statement. all procedural statements following this statement. When the option is selected by the user.5 PIC X(20) The above example occupies an area of the screen from 82 . This variant of the OPTION statement is valid in the DETAIL section of a FORM-ENTRY screen. no other procedural code within the screen is executed.col] [SECURITY [LEVEL] [IS] number] [WHEN condition] [HELP [IS] expression] [LOG [literal-string]] [SCALE [IS] expression] [COLOUR [IS] colour [ON colour]] [BOLD] [ITALIC] [UNDERLINED] [BITMAP [IS] expression [BITMAP-PUSHED [IS] expression] [BITMAP-FOCUS [IS] expression]] [NO-ASPECT-RATIO] [BITMAP-HOVER [IS] file-name] [ICON [IS] icon-name] [BUTTON-STYLE [IS] button-style] [DEFAULT-BUTTON [IS] expression] [TEXT-POSITION [IS] expression] [HOT-KEY [IS] expression] [HIDDEN] [ABSOLUTE-COORDINATES] [NO-THEME] OPTION standard-option-clauses [DETAIL] procedural-statements END-OPTION Clauses @row.col Screen co-ordinates to position option description. For example: @10.999.2 Whilst decimal places are supported. For example: DISPLAY ws-text @10.5.30.  A button (option) on the screen (second syntax variant below).0. the co-ordinate addressing is still based on a character grid. are performed. Decimal places are supported within the co-ordinates. Note: Valid (and unique) screen co-ordinates are currently required even if the menu is displayed by default using a tree menu or popup menu.10. Syntax OPTION alpha-expression @row.0 to @10.999.10.OPTION Statement This statement is used to implement either:  A selection (option) within a menu (first syntax variant below).10 PIC X(20) The above example occupies an area of the screen from @10.col [TO @row.5. however. that area includes a full character cell position to the bottom right of the end co-ordinate. or the end of the MENU. The row and column values can be arithmetic expressions. DISPLAY ws-text @10. Unless otherwise specified. it is currently not supported within data grids or review screens. all procedural statements prior to the ENDOPTION clause are performed.19. When the option is selected by the user. when an area of the screen is addressed. This applies to the user’s global security level number. but will wrap within the bounds of the button.80 The above example refers to an area from @1. SECURITY Specifies the security level for the option.col  The co-ordinate for the origin of the screen (that is.4999. For example: COLOUR IS RED ON 0 The standard PRONTO-Xi colours are supported. This will write an entry to the menu log file (menu. This allows a button based menu option to extend over more than a single line. Either the foreground colour only or both the foreground and background colours can be specified.9999 WINDOW @1. the button will be hidden from the screen.  The REFRESH statement can be used to update the display after changing the width or height of an OPTION button. Text with a scaling factor is vertically centred and will not wrap if larger than the width of the button. Note: TO @row.bmp" @10. Text without a scaling factor is not centred.999.999.20 The above example occupies an area of the screen from @10.5 to @11. The REFRESH statement can be used to update the display after changing the scale of an OPTION button.0. otherwise the menu option prompt will be used. COLOUR or COLOR For example: COLOUR IS RED ON BLACK COLOUR IS BLUE When ‘0’ or no colour is specified the user’s default colours will be used.0. The scaling factor is specified as a percentage (100 being normal font size).log) contained in the PRONTO-Xi lib directory.20.1 not @0. it will be removed after the screen is re-displayed using the REFRESH statement. HELP Defines a help line for the options. Note: Application security no longer uses the global [email protected]. This is the co-ordinate of the opposite corner of the button.80. DISPLAY BITMAP "abcd. If literal-string is specified then this will be used as the description of the menu option. WHEN This option will only be allowed when the condition specified is true. This option is ignored when a tree menu or popup menu is used.10 to @14. If the button had previously been shown.  When either of the row or column co-ordinates are negative. for example @-1.5. Secondary co-ordinates for the menu option’s button. Only users with a security level of at least this will be allowed to select this option.31.9999.0.0 to @23. The colours can be specified 83 . SCALE Scaling factor for the text’s font size when displayed within a button based menu.10. top/left) is @1.10 TO @14. LOG Log the selection of this menu option.4999.1 TO @23. but this will only be used on a characterbased terminal. Only Microsoft supported bitmap formats (for example. There are three bitmaps that can be specified. If they are not in one of the PROPATH directories a full path name to the bitmap file must be specified in order for it to be found. Fields storing colours must be at least PIC 9(5).bmp" BITMAP-FOCUS IS "deb/debf. it is the current button). unless the NO-ASPECT-RATIO clause is specified. The aspect ration of the bitmap will be preserved if any scaling is performed. but it is advisable to specify the others. The bitmaps specified for the OPTION statement are considered part of the application software. italic and underline can be used to alter the way text is displayed within the button. BITMAP Specifies a bitmap to be used for the OPTION statement when shown in a button-based menu. The BITMAP-PUSHED clause specifies the bitmap to be used when the button is pushed/pressed. Only the BITMAP clause is required.20 HELP IS "The Accounts Receivable module" BITMAP IS "deb/deb. BITMAP-HOVER Used to specify a bitmap to be displayed when the mouse pointer is hovering (or floating) over the button.bmp" The NO-ASPECT-RATIO clause can be used to indicate the aspect ratio of the bitmap is not to be maintained if the bitmap is stretched or shrunk. For example: BITMAP-HOVER IS "hover.as an expression (and hence can be varied at runtime).bmp" ICON The icon used in screen and tree menu based buttons can be specified using the ICON clause on the OPTION statement. no TO coordinate is given to specify an area. A prompt must still be specified for the OPTION statement.bmp" BITMAP-PUSHED IS "deb/debp. That is. The following predefined icon types are available: FOLDER-ICON ADMIN-FOLDER-ICON 84 . That is. this co-ordinate refers to the location of the top left corner of the bitmap. BOLD ITALIC UNDERLINED Bold. the bitmap will be stretched/shrunk both vertically and horizontally to fully fit the specified area. then the button will be show in a hyperlink style. The BITMAP clause specifies the normal bitmap for the option. BMP and JPEG) are currently supported. They should normally be contained in one of the directories specified in the PROPATH environment list. TYPE IS COLOUR) can be used. If the UNDERLINE attribute is used on an OPTION statement that does not specify a bitmap. If a TO co-ordinate is specified. All three bitmaps must be the same size. They will be searched for in the same manner as any application program. If the bitmap is smaller than the area it will be stretched to fit within the area specified for the bitmap. If a single co-ordinate is specified. For example: OPTION "A/R" @3. the bitmap will be scaled down (if needed) to fit within the specified area. The BITMAP-FOCUS clause specifies the bitmap to be used when the focus is on the button (that is. A field type of COLOUR (for example. For example: SET option-title = "TESTING" SET icon-number = SCREEN-ICON . OPTION OPTION-TITLE @10.. The MODE declaration. For example: SET my-button-style = CHECK_BOX_STYLE + BOLD_STYLE + ITALIC_STYLE .. however. the following highlight attributes can also be used: UNDERLINE_STYLE BOLD_STYLE ITALIC_STYLE Multiple highlight attributes can be specified.10 ICON IS SCREEN-ICON The OPTION statement allows the icon type to be specified by a numeric expression (or field name) to allow for variable options. OPTION "Test Button" @10.10 BUTTON-STYLE IS my-button-style The STANDARD_BUTTON_STYLE is required if UNDERLINE_STYLE is specified because underline by itself is a borderless hyperlink button style. does not allow expressions. The button styles are specified as one of the following defined values: RADIO_BUTTON_STYLE RADIO_BUTTON_SET_STYLE CHECK_BOX_STYLE CHECK_BOX_SET_STYLE TAB_BUTTON_STYLE ACTIVE_TAB_BUTTON_STYLE NO_BORDER_STYLE STANDARD_BUTTON_STYLE In addition to button styles. BUTTON-STYLE Allows the program to dynamically control the style and some highlight attributes of the button. 85 .. They will inherit the internal colour of the box overlaid.10 ICON IS icon-number Note: An extra two characters are added to the width of the button to allow for the size of the icon if the width is not specified.. Tab buttons are intended to overlay the top of a BOX by a single pixel.REPORT-FOLDER-ICON ADMIN-ICON REPORT-ICON SCREEN-ICON TRANSACTION-ICON PERIOD-END-ICON QUESTION-ICON BLANK-ICON FAVOURITES-FOLDER-ICON LOCKED-FOLDER-ICON BLUE-FOLDER-ICON RED-FOLDER-ICON GREEN-FOLDER-ICON ENQUIRY-FOLDER-ICON For example: OPTION "TESTING" @10. HIDDEN Used to indicate the option is hidden (non-display). If the BITMAP clause is also used. The numbers are based on the following grids: 1 2 3 4 5 6 7 8 9 Or 11 12 13 14 15 16 17 18 19 Where 1:11 means top/left. then a TEXT-POSITION value greater than zero indicates that the text for the Option is to be overlaid on top of the bitmap.30 TEXT-POSITION IS 15 HOT-KEY Used to specify a hot key that is to be associated with the option. When the hot key is pressed the OPTION is activated (depending on any WHEN condition). The clause has no effect if the menu is shown in a tree or popup format.For example: BOX @11 . For example: HOT-KEY IS 5 Note: Hot keys are not processed in popup menus. 2:12 means top/centre and so on. The text must specify the line breaks using “<br>” tags.10 TO @10. DEFAULTBUTTON Allows the specification of the default button for traditional button based menu. OPTION "Tab 1" @10. Currently only function keys (F1 . however.10 DEFAULT-BUTTON IS TRUE TEXT-POSITION Allows the location of text within the button to be specified for the Option. Note: PRONTO-Xi Thin Client 6. If multiple OPTION statements have a DEFAULT-BUTTON clause which evaluates to TRUE. Position numbers between 11 and 19 indicate that the text is to be displayed in multiple lines.10 TO @14.F24) can be specified as hot keys.15 BUTTON-STYLE IS tab1-style A REFRESH statement must be issued to refresh the displayed styles of a button when they change. the first one identified will be used. Co-ordinates are optional if HIDDEN is specified. rather than being ignored.7v0.5 or later is required. the option text is still required. The area specified does not include any part of the screen below or to 86 . The numeric codes to identify the function keys are the same as the function key number (that is. The position for the text is specified directly after this clause as a number between 1 to 9 or 11 to 19.40 ABSOLUTE-COORDINATES . if specified. For example: OPTION "Testing" @10. the code for F5 is 5).2 TO @23... The primary intention for this clause is for use with the HOT-KEY clause to enable hot key functions without displayed a button.(1 / GET-SYSTEM-METRICS(2)). The clause requires a conditional Boolean numeric expression to indicate either true or false. For example: OPTION "This is<br>a three line<br>button" @10. ABSOLUTECOORDINATES Affects the interpretation of the TO co-ordinate. This statement can be used to implement button logic that is available when the user is either at mode selection or in [Entry]/[Correct] mode. it does not form part of the logic of the DETAIL section and therefore will not affect the logic flow of the DETAIL section.20 ABSOLUTE-COORDINATES The above example occupies an area of the screen from @10. The WHEN clause of the OPTION statement should be used to flag when the option is valid. NEED PAUSE Statement This statement displays an [OK] button at the bottom right hand corner of the current window. If the prompt does not specify a selection character explicitly. NO-FOOTER Do not perform the page footer procedure before the new page. “E&xit” specifies x). if used. The END-OPTION statement is needed to identify the end of the statements associated with the OPTION statement. this clause will draw the button using a ‘classic’ button style). The character required to select the OPTION can be specified by prefixing the character with an ampersand (&) in the prompt (for example. Syntax PAUSE 87 . To print a single ampersand a double ampersand (&&) must be specified in the prompt. Syntax Clauses See Also PAGE [NO-HEADER] [NO-FOOTER] [ON report-name] NO-HEADER Do not perform the page header procedure for the new page. ON ON report-name. REPORT. SKIP. the first printable character in the prompt will be used. Notes (second syntax variant) Although the OPTION statement is specified within the DETAIL section of a screen. For example: DISPLAY BITMAP "abcd.10 TO @14.20 only. Processing will not continue until the button is pressed. Notes (first syntax variant) NO-THEME Used to disable the drawing of the button using the defined XP theme (that is.the right of the TO co-ordinate. PRINT. That is. Only mouse control is currently implemented. SCREEN PAGE Statement Force a new page for the report. See Also MENU . indicates that this print operation is only for the specified report. standard-optionclauses One or more of the clauses (from SECURITY through to NOTHEME) in the first syntax variant of this statement.bmp" @10. it does not allow for the additional character position. There is currently no way to invoke or navigate to an OPTION button via a keyboard.10 to @14. ]] [LEAVING ALL] POP field-name1 [. 88 .] FROM object-name Clauses Notes LEAVING Specifies a set of fields whose value should not be affected. The top most set of fields saved on the stack is restored (and removed from the stack). if LAST is used). NO-WARNING Suppress warning message if LAST option used. It is the responsibility of the program to ensure that all PUSH statements have a corresponding POP statement that is executed. BEFORE Position the object before the key value specified. Fields not in this list will remain unchanged.. AFTER Position the object after the specified key value. See Also PUSH. If no field values are required. the ALL clause can be used. The index used will be the first index found with the specified leading fields. The ON INDEX clause: A field list if specified only needs to match the leading fields of a valid index. LAST Position the object after the last record for the specified index. INITIALISE POSITION Statement Position the object at a particular record. If the record does not exist. field-name2 . If the stack of PUSHed records for the object is empty then the fields will be reset to their initial null values. When a key value is specified. Syntax POP object-name [LEAVING field-name1 [. Syntax Clauses Notes POSITION [BEFORE|AFTER] object-name [ON INDEX index] [KEY [IS] expression . You will be positioned directly before the record (or after. SAVE. RESTORE.] [FIRST|LAST] [NO-WARNING] ON INDEX Position using this index. The BEFORE/AFTER clauses must occur directly after the POSITION statement to avoid confusion with other uses of these words.POP Statement Restore the values of all fields previously saved for an object using the PUSH statement. LAST. The POSITION statement does not give you currency on the specified record if it exists. this is the default... you will be positioned where the record would have been if it did. KEY Position the object before the first record with a key value greater than or equal to that specified.. If none of the above clauses are specified then the object will be positioned before the first record with a key value greater than or equal to the current key field values. field-name2 . If no ON INDEX clause is specified then the index will default to 1. FROM Specifies a list of fields whose value is to be restored. FIRST Position the object before the first record for the specified index. Only one of the FIRST... or KEY clauses can be used. 89 . CLOSE. SUPERSCRIPT Print this expression in superscript mode. . DELETE. GET. SUBSCRIPT Print this expression in subscript mode. These clauses cannot be used in conjunction with a PICTURE clause. Can only be used if the report has the FULL-PAGE clause in effect. @ Specify the actual row and column position to print on the page. BLANKDECIMALSWHEN-ZERO The BLANK-DECIMALS-WHEN-ZERO clause generates a PICTURE that will display blanks where the decimal places would normally be displayed. SERIAL PRINT Statement Print the result of an expression on the report. ITALIC Print this expression in italics. See Also OBJECT. if the decimal places are zero. [NO-NEWLINE] [ON report-name] expression A valid numeric or string expression.col] [PIC [IS] picture] [BLANK-WHEN-ZERO] [BLANK-WHEN-DECIMALS-ZERO] [BOLD] [UNDERLINED] [ITALIC] [SUBSCRIPT|SUPERSCRIPT] [FONT number] [STATIC] [COLOUR [IS] colour [ON colour]] [SCALE [IS] scaling-factor] [LEFT|RIGHT|CENTRE] [SECTION [IS] alpha-literal] [TAG [IS] alpha-literal] expression . Values do not need to be specified for each of the fields in the index used. . This can be an expression that is evaluated at runtime. COLUMN Prints the expression at the specified column on the current line. INSERT.If a partial field list is used for the ON INDEX clause. The operation will act as though the real index only contained the leading fields that correspond to the number of specified key values. UNLOCK. UNDERLINED Print this expression with underlining. PICTURE or PIC Prints the result of the expression using this format rather than the default format. the operation will act as though the real index only contained the specified fields. EXTRACT. OPEN. BLANK-WHENZERO The BLANK-WHEN-ZERO clause generates a PICTURE that will display blanks if the value is zero. Syntax Clauses PRINT expression [[IN] COLUMN n] [@row. UPDATE. BOLD Print this expression in bold mode. ON ON report-name. but are defined within the ‘. The default XML tag for a single field is its name. Line overflow (printing passed the right margin of the report) will only be reported if you exceed 132 columns. The line will not be printed until the occurrence of a SKIP statement.xls’ file (style sheet). care must be taken if both these clauses are used. if used. some attributes contradict others. LEFT RIGHT CENTRE Notes The LEFT. For example: PRINT "xyz" TAG IS "xyz-tag" SECTION IS "xyz-sect" Note: There are specific rules for tag names in the XML specification. PAGE statement or another PRINT statement (without the NO-NEWLINE clause). indicates that this print operation is only for the specified report. SCALE Scaling factor for text. If the specified font number is not present for a printer. Note: This clause is not currently implemented. This only has effect in full XML reports. It indicates that this item will always contain the same contents within this line of the current section. RIGHT and CENTRE clauses control the justification of text. 90 . however. only text items should be specified as static. NO-NEWLINE Do not print this line yet.xml’ file. Note: Due to the conflict between the use of the ON keyword in the COLOUR clause and its use within the PRINT statement to specify a named report. For example: PRINT "xyz" IN COL 1 SECTION IS "xyz-sect" is equivalent to: REPORT SECTION IS "xyz-sect" PRINT "xyz" IN COL 1 REPORT SECTION FINISHED TAG The TAG clause can be used to override the default XML tag for an item being printed. the next lowest valid font number will be used. SECTION The SECTION clause on the PRINT statement is a shorthand way of defining a single line section. COLOUR or COLOR The COLOUR clause allows the specification of foreground and background colours for individual items within a PRINT line. Multiple print attributes can be used. Fonts can be numbered from 0 to 15 inclusive. No error will be reported for such occurrences. text or expression) in the PRINT statement. This limitation is due to the non-association of PRINT statements with the definition of the report (see the ‘REPORT Statement’). The meaning of a font number is site and printer specific. Static items are not written to the ‘. Generally. STATIC The STATIC clause is associated with the previous item (field. Characters such as ‘:’ have a special meaning (in this case a namespace) and ‘/’ are not allowed. Default tags for text and expressions/functions are internally generated. Either ensure that a background colour is always specified or do not place the COLOUR clause directly before the ON clause for the report’s name.FONT number Print this expression using the specified font number (specified as number). Each PUSH statement must have an associated POP statement executed. SKIP. PAGE PUSH Statement Temporarily save the current values of all fields contained in the specified object.The attributes that are printed depend upon the capabilities of the destination printer and its defined printer capabilities. SAVE. The values can be restored using the POP statement. RESTORE. INITIALISE QUERY Statement Execute the specified SQL query. The numbering of fonts is entirely user definable and inherently non-transportable. 91 .] [HOME [IS] alpha-expression] [BATCH] [NO-PAUSE] [SPOOL] [MAX-PARAMETERS numeric-expression] [ON ERROR procedural-statements [ELSE procedural-statements] END-ON] query-name This is the name of the query to execute. The query name should be relative to one of the directories specified in the PROPATH environment variable. See Also REPORT. PARAMETERS List of parameters to pass to the query. NEED. It can be any valid alphanumeric expression. Syntax Clauses QUERY query-name [PARAMETER[S] [IS|ARE] alpha-expression . If not. it will be possible for a POP operation to retrieve a different record than it is expecting. A recommended way to ensure this is to place the PUSH and POP statements around a DO statement.. For example: PUSH my-object DO my-process POP my-object See Also POP.. HOME Execute the query with this home directory. NO-PAUSE Do not pause after the query has successfully completed. Syntax Notes PUSH object-name It is the responsibility of the application to ensure that the stack of PUSHed records is correctly maintained. Only alphanumeric parameters can be passed. BATCH Submit this query to queue number zero of the PRONTO-Xi batch queue. The field values are pushed onto the top of a stack of saved records for this object. The program will not wait for the query to be performed. col expr TITLE title-expr COLOUR colour-name [@row. The PARAMETERS clause of the CALL/QUERY/COMMAND statements allows numeric values to be specified. numeric values will automatically be converted into their preferred alphanumeric format when passed.. The PARAMETERS clause does not need to define all expected parameters. SPL. This is considered a logic error within the application and should be avoided. Syntax Clauses RADIO-BUTTON field-name @row. DO. REPORT RADIO-BUTTON Statement This statement is used to add radio buttons to a screen. See Also COMMAND. This statement is only valid for FORM-ENTRY screens. If this option is specified then the report will be automatically spooled to a report file without asking. or the default value does not match one of the values in the list. if the value of the field does not match one of the values in the list.Notes SPOOL By default you will be asked whether to display the report on the screen or to spool it to a report file. ON ERROR Perform these statements if the query specified could not be executed. If the initial routine of the child program contains the PARAMETERS clause. For further information on FORM-ENTRY screens refer to the ‘SCREEN Declaration’ section. The word ENQUIRY is a synonym for QUERY. however. 92 . then the value of the first radio button in the list will be used as the default in [Entry] mode. BUTTON-WHEN tmp-field-1 NOT IN {'A' OR 'B'} RIGHT-COORDINATE [DEFAULT [IS] expression]] [WHEN expression] [READ-ONLY] [BEFORE-RADIO-BUTTON procedural-statements END-BEFORE-RADIO-BUTTON] [VALIDATIONS procedural-statements END-VALIDATIONS] [ON CHANGE default-value END-ON] [END-RADIO-BUTTON] DEFAULT The DEFAULT clause is used to populate the default value for the field when processed in [Entry] mode. then parameter values passed will be automatically moved into these fields (with the appropriate data conversions performed where necessary). regardless of the number of parameters specified.. Parameters for external programs are still passed in alphanumeric format. If no default value is specified. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the operation was successful. which evaluates to the maximum number of parameters to be passed. MAXPARAMETERS This clause allows a numeric expression to be specified. then no radio button will be shown as selected. A runtime error will result if too few parameters are passed to the child program. For the [Correct] and [Show] modes.col] expr TITLE title-expr . ON CHANGE This section is only available if the ACCEPT. Syntax Clauses RE-ENTER [field-name] [OPTIONAL|AUTO] OPTIONAL You are not forced to enter a new value for the field. When specified for a RADIO-BUTTON or CHECK-BOX. the radio buttons box will be greyed out on the screen. thus allowing a different text colour to be specified for each button. Whenever the value of a field changes this section will be invoked. This clause is specified against a specific TITLE for a radio button. Notes If a WHEN condition is specified and is false. This clause can be specified for each button in the radio button set. The RE-ENTER Statement and REFRESH Statement are valid for RADIO-BUTTON fields. Any validations will always be performed prior to the ON CHANGE section. The field’s current value will be used as the default. Should any validations fail. RE-ENTER Statement This statement transfers control back to the previous ACCEPT statement in the screen. COLOUR or COLOR Changes the colour of the title for the radio button. then the ON CHANGE section will not be invoked. Note: If the field is subscripted the field’s name should be specified without any subscripting.BUTTON-WHEN Conditionally enable or disable individual buttons. then the value of the field will not be validated. RIGHTCOORDINATE The specified coordinates are for the button to be positioned on the right side of the button title. AUTO See Also Automatic re-entry of the field. RADIO-BUTTON and CHECK-BOX statements are within a FORM-ENTRY screen. This occurs regardless of the previous value of the fields. this section will be invoked immediately when the user changes the value of the radio button or check box. ACCEPT 93 . This clause will flag that all validations specified for the ACCEPT of that field should be applied to the field’s current value. The fields current value is retained and the ACCEPT and its validations are processed again automatically without user intervention. If the BUTTON-WHEN clause is specified for every button in the set and it is false for each button. If the OPTIONAL clause is omitted you will be forced to enter a new value (if the ACCEPT does not have a DEFAULT). This section will be automatically invoked at the beginning of [Entry] mode when the initial value of the fields are set to their default values. The format for this clause is the same as for an ACCEPT. The WHEN clause should still be used to enable/disable the entire set of buttons. Radio buttons cannot be used (are invalid) in data grids or review screens. If a field-name is specified then control is transferred to the previous ACCEPT statement for that field in the screen. then displays any prompts/titles for ACCEPT or OPTION statements in the DETAIL section. PROMPTS Only re-display the prompts for the screen/menu. REVIEW Re-display the entire screen of review/data-grid records. CLEAR REPEAT Statement This statement is a procedural looping construct similar to the WHILE statement. The field must be contained in an ACCEPT within the DETAIL section.REFRESH Statement Refresh (re-display) either the current screen (or menu). Syntax Notes REPEAT procedural-code-1 UNTIL logical-expression procedural-code-2 END-REPEAT The UNTIL condition is the opposite tense to the WHILE condition. This does not take place until the DETAIL section of the SCREEN has completed. CONTINUE. This processes the DETAIL command group in [Show] mode. Syntax REPORT [report-title] [FILE [IS] file-name] [DIRECT [TO] printer-name] [NAME IS report-name] [HEADER [IS] procedure-name] [FOOTER [IS] procedure-name] 94 . field-name Only re-display the value of the specified field name. the loop will terminate when the condition is true. That is. Two sections of procedural code are specified. The ACCEPT statement containing the field can be specified after the REFRESH statement. The first will always execute initially regardless of the condition. The application must issue one of these statements if it wants to force the SELECT for the screen to reflect any change it has made to the current record location of the object(s) associated with the SELECT. See Also ACCEPT. DISPLAY. A REFRESH DATA (on a non data-grid/review screen) or a REFRESH REVIEW will cause a repositioning of the current record within the SELECT for the screen. but after this both sections are conditional. See Also FOR. Syntax Clauses Notes REFRESH [DATA|PROMPTS|REVIEW|field-name] DATA Only re-display current field values for the screen/menu. If no clauses are specified then the SCREEN will be refreshed by processing the BEFORE and DETAIL sections in [Show] mode. or the specified field. This processes the BEFORE command group in [Show] mode. BREAK REPORT Statement Start/finish a report. A CONTINUE statement will continue execution at the start of the procedural code in the first section. WHILE. Note: Only one DIRECT report can be active at any one time. file-name can be any valid alphanumeric expression. Note: The header is not automatically performed at the start of the report. If it is required there it must be forced using the PAGE statement. FILE A report by default is written to a file with an automatically generated (random) file name. If there is no DEPTH or LENGTH specified then a default depth of 60 will be used. If multiple DIRECT reports are required simultaneously. Note: The footer is not automatically performed at the end of the report. HEADER Defines a procedure to perform at the start of every new page. If not specified the width is assumed to be 132 characters.[WIDTH [IS] expression] [DEPTH [IS] expression] [LENGTH [IS] expression] [MARGIN [IS] expression] [DEFAULT FONT [IS] expression] [FULL-PAGE] [FORM TYPE [IS] alpha-literal] [NO-XML] [SPOOL-ONLY] [FULL-XML] [NO-MESSAGE] [ON ERROR procedural-statements [ELSE procedural-statements] END-ON] REPORT FINISHED [ON report-name] Clauses report-title An alphanumeric expression that identifies the title of the report. 95 . that is. When this line is reached the page footer (if defined) will be automatically performed and a new page generated. The name specified must be a valid identifier name. WIDTH Defines the width of the report. the report name must be unique to that report. the same report-name cannot be used in multiple REPORT statements. NAME Specifies an identifier name associated with this report. printer-name can be any valid alphanumeric expression. REPORT names cannot be duplicated. the report will be spooled directly to the specified printer. FOOTER Defines a procedure to perform at the end of every page. finish the active report before starting the next. If this clause is specified. If not specified then a default depth of 6 lines less than the LENGTH will be used. This name can be referred to in any of the valid report operations. The depth value cannot exceed the report’s length. This name can be referred to by any of the valid report operations. If this clause is specified the report will be written to a file of the specified name. REPORT names cannot be duplicated. If it is required there it must be forced using a PAGE statement. that is. DEPTH This is the number of the last line to be used for normal printing. DIRECT Reports are by default written to a file for later printing. NAME IS The NAME IS <report-name> can be used to identify a specific report. PAGE. DEFAULT FONT This is the default font to use when no other is specified in a PRINT statement. if the printer has this capability. If FULL-XML is used then any customized style sheet or customized CSS file for this report must be named based on this form type. change your current unnamed report) by re-executing the REPORT statement that created the required report. The report will be generated in the traditional (older style) report format (that is. Fonts can be numbered from 0 to 15 inclusive. This does not apply for reports with the NAME clause specified.xsl’ extension. FINISHED Flag that the current report is finished. but only one unnamed report can be active (current) at any one time since a PRINT. PRONTO-Xi will search for a customised style sheet.css’ extension. If not specified the margin is assumed to be zero. #P format). MARGIN Defines the margin for the report. If this is not specified then the current report will be automatically finished upon termination of the program. NEED or SKIP statement without the ON clause is not associated with a particular report. FULL-XML The FULL-XML clause on a REPORT statement indicates that the report will be generated as a fully compliant XML/XSL report. The printer which the report is sent to will have its form length automatically set to the amount specified. NO-MESSAGE Normally when a spool file is created a message indicating this fact is displayed on the screen. Multiple unnamed reports can be defined in a program. SPOOL-ONLY The SPOOL-ONLY clause on a REPORT statement specifies that the XML viewer should not be automatically invoked to view the report. Customised style sheets are contained within a ‘custom_xsl’ directory. Line and column coordinates can be specified in the PRINT statement using the @ clause similar to the DISPLAY statement. FULL-PAGE The FULL-PAGE clause allows the full page of the report to be addressable when printing. This requires all XML sections to be identified within the report by use of the REPORT SECTION statement and the SECTION clause on the PRINT statement. if used. The name of the customised style sheet searched for is that of the form type with a ‘. FORM TYPE This is the name to be given to the form type for this report. If multiple unnamed reports are required to be generated simultaneously you can switch between reports (that is. The FILE-STATUS() function can be used to return the number of the error. or customised cascading style sheet (CSS) for the report. Font zero is assumed to be the default font unless this clause is used. Customised CSS files and style sheets: At the point of generating a new XML report. This clause. Notes NO-XML The NO-XML clause can be used to disable XML/XSL reporting for a report. ON ERROR Perform these statements if the report specified could not be generated. will inhibit the displaying of this message. if used. indicates that this print operation is only for the specified report. based on the name of the specified form type. The customised CSS file name is that of the form type with a ‘.LENGTH Defines the page/form length of the report. Customised CSS 96 . If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the operation was successful. ON ON report-name. SKIP. COLOUR or COLOR Used to specify the default foreground and background colours to use within this section. or .css’ will be searched for. If a customised style sheet is found for the form type then a customised CSS file will not be searched for. STYLE-CLASS Specifies the name of a CSS (cascading style sheet) class name for the section.. NEED. CAN-HIDE Indicates that the contents of this section will be shown by default. FINISHED Finish the current report section. If the section string does not start with a / or \. PAGE. The previous line in the report (contained in the parent section) will show a button to allow this section to be expanded. a customised CSS file will still be searched for. See Also REPORT. Be default.files are contained within a ‘custom_css’ directory. \. 4) Within the $BMS directory.” refers to the parent section. The FINISHED clause is equivalent to writing: REPORT SECTION IS “. A closed section can only be started again.css’ will be searched for. otherwise a CSS file called ‘basic-xml. 2) Within the current report directory (if different from data directory).” RE-SELECT Statement This statement can be used in a SCREEN that uses a SELECT or PRIMARY clause. HIDDEN Indicates that the contents of this section will not be shown by default.. the section string should not contain /. but can also be closed/hidden. If the FULL-XML clause was specified then a CSS file called ‘full-xml. characters. SECTION. This is used to generate a path name within the XML file.. A section named “. These directories are searched for in the following locations: 1) Within the current data directory. A section once closed cannot be re-opened (that is. 97 . Syntax REPORT SECTION [IS] [section-name] [HIDDEN|CAN-HIDE] [COLOUR [IS] colour [ON colour]] [STYLE-CLASS [IS] alpha-expression] [ON report-name] REPORT SECTION FINISHED [ON report-name] Clauses section-name Can be any valid alphanumeric expression or string. It is advised that 3-4 characters be allowed at the start of the previous line for the button. it will be added to the current XML path. If no form type is specified for a report. 3) Within the $PRONTO directory (or $NETPRONTO if Windows O/S). QUERY REPORT SECTION Statement Marks the start (or finish) of an XML section within the report. The previous line in the report will show a button to allow this section to the closed. continued). PRINT. UPDATE ROLLBACK WORK Statement This is equivalent to the TRANSACTION ROLLBACK statement. Syntax RESTORE object-name [LEAVING field-name1 [. POP. UPDATE SELECT Statement The SELECT statement is a procedural looping structure that reads rows from the specified table or tables. INITIALISE.The RE-SELECT statement restarts the SELECT operation. Any sorting required will be performed again. DELETE...]] RESTORE field-name1 [. DELETE. Syntax SELECT select-clauses [BEFORE [field-list] procedural-statements] [DETAIL procedural-statements] [AFTER [field-list] procedural-statements] 98 . The saved values are not altered by the RESTORE operation. See Also SAVE. field-name2 . INSERT. The values can be restored using the RESTORE statement. Syntax RE-SELECT RESTORE Statement Restore the values of all fields previously saved for an object using the SAVE statement. GET.] FROM object-name Clauses LEAVING Specifies a set of fields whose value should not be affected. This statement may be required in SCREENs that use a SELECT and insert or modify records outside of the control of the screen. INSERT. INITIALISE. Fields not in this list will remain unchanged. For further details refer to the ‘TRANSACTION Statement’ section. field-name2 . Syntax See Also SAVE object-name RESTORE. PUSH. GET. Notes The second syntax of this statement allows the specification of a list of fields whose value is to be restored. Each row returned forms one iteration of the loop. The list of records SELECTed may not show records inserted after the SELECT was started in some implementations (for example. If there were no values previously saved for the object then the fields will be reset to their initial null values. aggregate values will be reset.. etc. Any previously saved values will be overwritten. Syntax ROLLBACK WORK SAVE Statement Temporarily save the values of all fields contained in the specified object.. The SAVE statement stores only one set of values. Only issuing another SAVE statement for that object alters them. relational database versions). . BEFORE [field-name . Notes The SELECT loop can abort with a fatal runtime error if the objects in the FROM list are referenced in another file I/O operation that would affect the current position of the object.] Specifies procedural code that will be performed before the DETAIL section when one or more of the specified fields changes its value.. See Also SELECT Clause. GET. An AFTER section specified without a field list will be performed once at the end of the SELECT loop if the SELECT loop processes rows. SET lf-save-flag = sol-print-line // first read backwards to a non DN. the IF statement within the DETAIL clause defines a ‘finish when’ condition. A BEFORE section specified without a field list will be performed once at the start of the SELECT loop if the SELECT loop processes rows. as the integrity of the SELECT loop cannot be guaranteed. AFTER [field-name . 99 . BREAK Code Example The following code demonstrates how to read backwards through a table. then break out of the select.. CONTINUE. The UPDATE and DELETE statements can be used on the row returned from a single table SELECT as long as the FOR UPDATE clause is also used.] Specifies procedural code that will be performed after the DETAIL section when one or more of the specified fields changes its value. The WHERE clause defines the starting position. It will not be performed if no rows are processed. This statement reads the specified object and gets the value of the specified field. BREAK ENDIF SET lf-save-start-line = sol-line-seq END-SELECT SERIAL Statement Serial number stream manipulation. Multiple AFTER sections can be used.. It will not be performed if no rows are processed. so we will edit all the notes! // // we are current on a s/o line so start reading backwards from here SELECT * FROM like-sales-order-line ORDER BY so-order-no DESC so-bo-suffix DESC sol-line-seq DESC WHERE (so-order-no = :lf-save-order-no AND so-bo-suffix = :lf-save-suffix) AND sol-line-seq < :lf-save-start-line DETAIL IF sol-line-type != 'DN' // no longer a note line OR sol-chg-type IN { 'T' 'D' } // is part of kit OR sol-print-line != lf-save-flag // diff print flag THEN //if the previous line is not a DN or it is part of //a kit or the print flag is different or the note //type is different. DETAIL Specifies procedural code that will be performed once for every selected row.END-SELECT Clauses select-clauses Refer to the ‘SELECT Clause’ section. The record is updated with the field’s value incremented by one (1). Multiple BEFORE sections can be used. EXTRACT. Current field values will be that of the new row. and the DESC option in the ORDER BY clause sorts the fields in descending order. Multiple DETAIL sections are not allowed. Current field values will be that of the previous row. Records can also be locked again after the SERIAL statement if this will not cause potential integrity issues (that is. CLOSE.Syntax Clauses Notes SERIAL object-name field-name [ON INDEX index] [KEY [IS] expression . the runtime will commit any automatically generated transaction that is in progress. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the operation succeeds. The field must be contained in an object referenced or a field declared in a FIELD statement.] procedural-statements [ELSE procedural-statements] END-ON] ON INDEX Read the object using this index number. Values do not need to be specified for each of the fields in the index used.* SET object-name. If no ON INDEX is specified then the index will default to 1. If a partial field list is used for the ON INDEX clause. A log of lost locks caused by the SERIAL statement can be obtained by setting the PROLOGLOSTLOCKS environment variable. POSITION. Syntax SET field-name assignment-operator expression SET array-name[*] = expression SET object-name. KEY Read the object using this key value otherwise use the current key value. unlocked) when the transaction is committed. SERIAL SET Statement Assign a value to a field. this may cause locking and/or deadlocking contention on the serial number stream since it will remain locked until the transaction is committed.* 100 .* = * SET * = object-name. GET.... The operation will act as though the real index only contained the leading fields that correspond to the number of specified key values. See Also OBJECT. This ensures that the serial number stream is not blocked. However. OPEN. logical locks on a header record). the operation will act as though the real index only contained the specified fields. UNLOCK. Applications which require locks to be retained after the SERIAL statement can enclose the SERIAL statement within an application specified transaction.] [ON ERROR [error-number . A consequence of this is that all existing locked records are released (that is. The index used will be the first index found with the specified leading fields. UPDATE. DELETE. Data Triggers: Triggers are not invoked as a result of the SERIAL statement.. The ON INDEX clause: A field list if specified only needs to match the leading fields of a valid index.* = object-name. ON ERROR [error-numbers] Defines procedural code to be executed if the operation fails. INSERT. RDBMS Implementations Only: If the SERIAL statement is performed outside of an application specified transaction. If TO is not specified then the number of lines specified are ignored. For example: SET abc-array[*] = 0 SET xyz-array[*] = "ABCD" This is the only place where an asterisk (*) can be specified as a subscript.SET PAGE-NO | DEFAULT FONT assignment-operator expression [ON report-name] Clauses expression Any valid alphanumeric or numeric expression. and can have arithmetic performed on them (for example. The following two SET statements are equivalent: SET a = a + (5 * b) SET a += 5 * b PAGE-NO Allow the alteration of the value returned by the PAGE-NO() function for a report. array-name[*] The SET statement allows the specification of an asterisk (*) as the subscript to the field being set. DEFAULT FONT Allows alteration of the default font value for a report. PRINT. A new page is forced if insufficient lines are left in the page. For example. If the ON clause is not used. Date and Time formats are considered numeric. then this statement applies to the current active unnamed report. Report-name must be a valid report name defined in the REPORT statement. See Also STRING SKIP Statement Disregard lines in the report. Notes Control characters (ASCII codes 1 to 31) can be stored in alphanumeric fields. This implies that every element of the array is to be set to the specified value. Syntax Clauses See Also SKIP [expression] [LINES] [ON report-name] SKIP TO [LINE] expression [ON report-name] TO Jump to the line number specified by expression. ON report-name If PAGENO or DEFAULT values are being altered then this clause is allowed to define which report is being referred to.* This allows objects defined with the NO-JOIN clause to move field values between other NO-JOIN objects containing some or all of the same fields. adding 1 to the date). PAGE 101 . REPORT. object. ON report-name The ON clause can be used to identify the report that this statement applies to. NEED. although their use is discouraged. += means add the value of the expression to the field. assignmentoperator The following assignment operators are supported: = += -= *= /= %= The combination assignment operators are a shorthand way of expressing a calculation that involves the field being SET. The type of expression (numeric or alphanumeric) must match that of the field. and between the global fields of the same name (using * by itself). APPENDING Append the result of alpha-expression to the end of alpha.field. See Also END-STATEMENT-GROUP STRING Statement Manipulate the contents of alphanumeric fields (type ALPHA and STRING). Syntax STATEMENT-GROUP Notes For future screen painters and other tools that manipulate source code. trailing blanks in this field will not be included. alpha-expression can be any valid alphanumeric expression. only the character at that position will be deleted. Trailing spaces in the result of the alpha-expression are included in the size calculation of the expression. The resultant size of alpha-expression determines the number of characters replaced. If a field type of STRING is specified as the expression for the INSERTING or REPLACING options. fields and literals. For further details refer to the ‘CALL Statement’ section. STATEMENT-GROUP Statement This statement can be used in conjunction with the END-STATEMENT-GROUP statement to mark a group of statements that must be kept together. Characters within the field can be inserted. replaced and appended. the intention of these statements will be to detect and honour the defined statement groups. 102 . The STATEMENT-GROUP and END-STATEMENT-GROUP statements have no impact on the execution of the program. If only one character position is specified. DELETING. DELETING Delete characters in alpha-field between the two character positions specified (inclusive). REPLACING and APPENDING clauses can be incorporated into the one STRING statement rather than specifying several STRING statements. Several INSERTING. deleted. Syntax Clauses Notes STRING alpha-field INSERTING|REPLACING alpha-expression AT position STRING alpha-field DELETING position [TO position] STRING alpha-field APPENDING alpha-expression INSERTING Insert the result of alpha-expression into alpha-field at the specified character position. The end of alpha-field is considered to be the last non-blank character contained. REPLACING Replace characters in alpha-field starting at character position ‘position’ with the result of alpha-expression. This includes alphanumeric functions.SPL Statement This is a synonym for the CALL statement. See Also SET SWITCH Statement The SWITCH statement is a more efficient and convenient way of conditionally performing statements depending upon the result of a single expression. or have no effect if unsuccessful.]] [LEAVING object [. If the LEAVING clause is specified then all objects 103 . FOR. The values must be single literal values (for example. .. Multiple values can be specified in the one CASE statement. ELSE See Also Specifies procedural statements to perform if the result of the expression does not match any of the values in the CASE statements.] procedural-statements] .] procedural-statements ELSE procedural-statements END] TRANSACTION ROLLBACK [ON ERROR [error-number . 123 or “ABC”) or screen mode names.. The TRANSACTION statement is used to mark the start and end of a logical transaction. Syntax TRANSACTION BEGIN [ON object [. If the ON clause is specified then only the list of objects specified will be logged..] procedural-statements [CASE value3 [value4 .Syntax Clauses SWITCH ON expression CASE value1 [value2 . WHILE. .] procedural-statements ELSE procedural-statements END] TRANSACTION COMMIT [ON ERROR [error-number . object ..] procedural-statements ELSE procedural-statements END] Clauses BEGIN This marks the start of a transaction... They cannot be field names or expressions.. [ELSE procedural-statements] END-SWITCH CASE Specifies the values of the expression that will cause the following procedural statements to be performed. Only INDEXED files will be logged.]] [FREE-LOCKS] [ON ERROR [error-number ... A logical transaction is a set of file operations that must either all succeed. REPEAT TRANSACTION Statement Transaction control handling. IF. The values must be compatible with the SWITCH expression. Only one transaction can be defined/active at a time.. object . This is done to ensure that the logical integrity of the data remains intact should a failure occur..... will be part of the transaction EXCEPT those specified in the clause. ON ERROR [error-numbers] Notes Statements to perform if an error occurred. and changes cannot be rolled back. The FREE-LOCKS clause can be used to alter this for C-ISAM based implementations. Other file types (for example. This ends the current transaction. Long running transactions can cause problems with other applications since all the records affected by the transaction are locked until its completion. UPDATE. the process of beginning and committing a transaction has an overhead. BEGIN WORK. All objects stored in the RDBMS that are processed during the transaction will form part of the transaction. If possible. All record locks held are released (unlocked) when a transaction begins. SEQUENTIAL) do not form part of the transaction. locks to “master” files should be deferred until late in the transaction to limit the time that they remain locked. See Also INSERT. The DBSEQUENTIAL file type also forms part of transactions on RDBMS systems. Note: The LEAVING and ON clauses have no effect in a relational database version. Any record locks generated during the transaction are released when it is either committed. unlock the current record for the specified object. updated and deleted during the transaction will remain locked until the transaction is completed (either committed or rolled back). COMMIT WORK and ROLLBACK WORK are synonyms for TRANSACTION BEGIN. This option has no effect for RDBMS implementations. TRANSACTION COMMIT and TRANSACTION ROLLBACK respectively. Syntax UNLOCK object-name UNLOCK ALL [LOCAL] Clauses ALL Unlock all locked records for every object referenced in the program. Only objects with the INDEXED (ISAM) file type form part of the transaction. It is only processed for C-ISAM based implementations. This ends the current transaction. update and delete operations are more efficient when enclosed within a transaction. Any record locks that are held at the start of a transaction will be released (unlocked) prior to the start of the transaction. or rolled back. ROLLBACK Specifies that the transaction is not successful and any changes made to the objects specified are to be undone. Processing the same data with many small transactions will be less efficient than processing it with fewer larger transactions. You should avoid transactions that are excessively long in either duration or records affected. COMMIT Specifies that the transaction is successful and all changes made to the objects specified are to be permanent. On most RDBMS implementations the insert. TEXT. DELETE UNLOCK Statement Unlocks the current record for the object specified or unlocks all locked records for all objects. FREE-LOCKS Free (release) locks on records affected by the transaction. as they would normally be released if processed outside of a transaction. otherwise. The current record of objects affected by the transaction cannot be guaranteed after a rollback. No error will result if there is no current record or if the record was not locked. 104 . All records inserted. However. OPEN. then the list of fields specified in the UPDATE statement must not include additional fields (not specified in the GET). SERIAL. SERIAL UPDATE Statement Updates the values of the current record for the object. The update will fail if the record is locked by another user. Position in the file is not altered if the key value is changed.] procedural-statements [ELSE procedural-statements] END-ON] field-list IN List of fields that form part of the update. If the error is not in the list then the program will abort with a full error detail screen. LOCK Retain the lock on the record once it is updated on file. GET. INSERT. Any key field values can be changed. INSERT. EXTRACT. POSITION. See Also OBJECT. See Also OBJECT. The update will fail if there is no current record or a key specified is unique and already present on file. UPDATE. If the current record was obtained by a GET statement that contained a field list. RESTORE 105 . Notes Locks will normally not be released for records that form part of a transaction until the transaction is complete..LOCAL This clause is used with the ALL clause. EXTRACT. The UNLOCK statement may have no effect during a transaction. OPEN. Syntax Clauses UPDATE [field-list IN] object-name [NO-WARNING] [LOCK] [ON ERROR [error-number . INITIALISE. If the ELSE clause is specified then the procedural statements following the ELSE will be performed if the UPDATE succeeds. Only the values for these fields will be updated in the record. The values of fields in the record that are not in this list will not be updated. The record will remain locked until explicitly unlocked or until it is no longer the current record. The record being updated must be locked prior to the update. This clause must occur prior to the LOCK and ON clauses. Notes There must be currency on the record that is being updated. DELETE. UNLOCK. The ON ERROR clause of any I/O operation can have a list of error numbers specified (directly after the ON ERROR). DELETE. GET. SELECT. ON ERROR [error-numbers] Procedural statements to perform if the UPDATE fails.. The ON ERROR section will only be performed if the error is one of those listed. POSITION. SAVE. CLOSE. NO-WARNING Do not give a warning regarding the possibility of the record not being locked. A runtime error will occur in this situation. that is: UNLOCK ALL LOCAL Specify this clause to only affect files in the current operations table. CLOSE. The number is intended to be incremented whenever the source file is modified. field.spl) should contain a version number string.789”.VERSION-NUMBER Statement Each 4GL source file (. SWITCH. or function. for example. They can be queried at runtime by pressing F9 (Session Information). WHILE Statement Repeatedly perform the procedural statements while the condition is true. for example EXTRACT.456. Syntax Notes VERSION-NUMBER [IS] version-number A program called ‘prowhat’ can be used to list the full version control information for a particular operations table. the expression will be evaluated with the following operator precedence: 106 . CONTINUE Expressions and Operators This section summarises the expressions and operators available in the PRONTO-RAD 4GL language. by a source code control facility. for example “123. See Also IF. BREAK. It can be specified as either a number or as a free format literal string. FOR. When an expression (or sub-expression) contains multiple operators. These can be classified into the following categories:  Arithmetic Expressions  Alphanumeric Expressions  Relational Expressions  Logical (Conditional) Expressions Arithmetic Expressions Syntax operand [arithmetic-operator arithmetic-expression] (operand [arithmetic-operator arithmetic-expression]) Arithmetic operators Operator precedenc + Add - Subtract * Multiply / Divide % Modulus (remainder) operand The operand can be any valid numeric literal. Syntax WHILE logical-expression [DETAIL] procedural-statements END-WHILE Clauses DETAIL Provided only for readability and consistency with other looping constructs. The compiler stores these numbers in the operations table it generates. text enclosed in quotes). The pattern can contain the following pattern matching characters: _ (underscore) This matches any single character. Alphanumeric Expressions Alphanumeric expressions consist of a single alphanumeric operand. % (percent) This matches zero or more characters. 107 . SET) where literal strings are considered to be pure data will require the use of the TRANSLATE keyword if language translation for the text is required. field or function. the TRANSLATE keyword can be used to indicate that the text should have language translation (mapping) performed on it. No operators (for example. For example: (10 + 2) * 4 evaluates to 48. or any valid alphanumeric expression. The pattern is specified as the expression immediately following the LIKE keyword. Alphanumeric operands are any valid alphanumeric literal (that is.e Highest precedence: * / % Lowest precedence: + Operators with the same precedence will be evaluated in the order that they are specified. For example: SET lf-prompt = TRANSLATE "Date of birth:" Relational Expressions A relational expression is a component part of a logical expression. Syntax Relational operators expression [[NOT] relational-operator expression] > Greater than < Less than = Equal to != Not equal to <> Not equal to >= Greater than or equal to <= Less than or equal to LIKE The value must match the specified pattern. When specifying an alphanumeric literal string. as translations will be automatically performed for literal strings used by statements (for example. For example: 10 + 2 * 4 evaluates to 18. Parenthesis (brackets) can be used to alter the order in which the operators are evaluated within an expression. The pattern can be specified as an alphanumeric literal string. DISPLAY) that are known to require translation. +) can be used. Other statements (for example. Operators with a higher precedence will be evaluated before operators with a lower precedence. This is not needed in most circumstances. rather than that of the database being used. the operator’s meaning is inverted. ‘A’ will equal ‘a’). NOT > becomes <=. The expression used within a relational expression can be any valid numeric or alphanumeric expression. In some databases this character may instead be listed prior to both alphanumeric and numeric characters in the sort order. If a pattern is to be stored in a field. Also. Logical (Conditional) Expressions Syntax [NOT] relational-expr [[logical-operator] logical-expr] [NOT] (relational-expr [[logical-operator] logical-expr]) Logical operators AND Both conditions must be true OR One or both conditions must be true 108 . For example: IF accountcode COLLATE > ws-end-accountcode THEN . This must also precede the ASCII or COLLATE keywords if used with the relational operator. uppercase and lowercase characters may be considered equivalent for comparison purposes (for example.. or both alphanumeric). The expressions on both sides of the relational operator must be compatible (that is. ENDIF The collating sequence of some databases may differ substantially from the ASCII character set. for example. either both numeric. This is the default for any alphanumeric comparison made in the WHERE condition of a SCREEN.. it is advised that the field be defined as TYPE STRING so that trailing spaces (blanks) in the field will be ignored when used as a pattern. (for example. ASCII The ASCII keyword can be prefixed immediately prior to any of the relational operators when comparing alphanumeric values. For example. SELECT clause or EXTRACT loop. This clause should be used if any range checking of key fields are performed outside of the WHERE conditions of a SELECT or EXTRACT loop.Note: Trailing spaces will be considered part of the pattern. COLLATE The COLLATE keyword can be prefixed immediately prior to any of the relational operators when comparing alphanumeric values. or as a result of the GET statement being used to retrieve a range of records. Characters with accents etc. in ASCII the tilde (~) is often the highest printable character. This is the default for any alphanumeric comparison that does not occur in the WHERE condition of a SCREEN. This indicates that the comparison should be based on the collating sequence (sort order) of the database being used. “”) may also be considered equivalent to the non-accent version of the character. For example. NOT General If prefixed immediately prior to any of the relational operators. This indicates that the comparison should be based on the ASCII character set collating sequence. there may be an equivalence of certain characters in the sort order. a SELECT clause or an EXTRACT loop. This can precede a logical expression to invert its result. the following two IF statements are equivalent: IF lf-true-false IF lf-true-false != 0 Combinatio n operators [NOT] BETWEEN value AND value This is a shorthand method of specifying a range. Parenthesis (brackets) can be used to alter the order in which the logical operators are evaluated within a logical expression. the failure of any condition will cause all other AND tests to be ignored as their results are irrelevant. For example: expr1 BETWEEN expr2 AND expr3 Is equivalent to expr1 >= expr2 AND expr1 <= expr3 [NOT] IN This is a shorthand method of testing for a set of values. When multiple AND conditions are present within a logical expression. when multiple OR conditions are present within a logical expression. When a logical expression (or sub-expression) contains multiple AND/OR operators. IF lf-sub > 0 AND lf-array[lf-sub] != 0 THEN .NOT Operator Precedence Unary not. the failure of the first condition will mean that the second condition will not be evaluated. AND conditions are evaluated before any OR conditions. otherwise it is false. expr4) Is equivalent to expr1 = expr2 OR expr1 = expr3 OR expr1 = expr4 PRONTO-RAD 4GL Functions The functions supported by the PRONTO-RAD compiler and runtime can be classified into the following categories:  Arithmetic Functions  Date Handling Functions  Environment Functions  String Handling Functions Arithmetic Functions PRONTO-RAD supports the following arithmetic functions: 109 . ENDIF A logical expression can also be constructed with a single arithmetic expression in place of a relational expression.. If the arithmetic expression evaluates to a non-zero amount then the result is considered to be true. ( values ) For example: expr1 IN (expr2. Similarly. the first successful condition will cause all following OR conditions to be ignored. For example. expr3. the logical expression will be evaluated with the following operator precedence: Highest precedence: AND Lowest precedence: OR That is. General The logical expression (or sub-expression) is evaluated from left to right. If it were to be evaluated a subscripting error would occur. For example.. 00 110 .) ABS() Returns the absolute (positive) value of a number. no bit positions are set (1) in both bytes.1 and above Example: SET gl-trans-amount = ABS(ws-invoice-amt) // // Result: Assuming ws-invoice-amt is -99.2) // // Result: ws-num = 0 // // 1001 (9) // 0010 (2) // ---------// 0000 (0) That is.00 and above Notes This function is not intended for general use. It returns a decimal number that is the equivalent binary number when the two binary numbers passed are arithmetically ‘ANDed’ together.00 then // gl-trans-amount will be 99. Syntax ABS(number) Category Arithmetic Runtime 3. bit positions 2 and 4 are set (1) in both bytes) Example: SET ws-num = AAND(9.AAND() LSHIFT() SMALLEST-INCREMENT() ABS() MAX-VALUE() SQUARE-ROOT() ANOT() MIN-VALUE() STR() AOR() POWEROF() SUM() COS() RANDOM() SUM-ARRAY() FRACTION() RSHIFT() TAN() GET-SYSTEM-METRICS() SIGN-OF() INTEGER() SIN() AAND() Returns the arithmetic (binary) AND of two binary numbers.binary_number) Category Arithmetic Runtime 3. Syntax AAND(binary_number.5) // // Result: ws-num = 5 // // 1101 (13) // 0101 (5) // ---------// 0101 (5) (ie. Example: SET ws-num = AAND(13. 2) // // Result: ws-num = 11 // // 1001 (9) // 0010 (2) // ---------// 1011 (11) COS() Returns the cosine of an angle specified in radians. It returns a decimal number that is the equivalent binary number when the two binary numbers passed are arithmetically ‘OR-ed’ together.5) // // Result: ws-num = 13 // // 1101 (13) // 0101 (5) // ---------// 1101 (13) Example: SET ws-num = AOR(9. Example: SET ws-num = ANOT(5) // // Result: ws-num = -6 // // 0000 0000 0000 0000 0000 0000 0000 0101 // ---------------------------------------// 1111 1111 1111 1111 1111 1111 1111 1010 AOR() Returns the arithmetic (binary) OR of two binary numbers. It returns a decimal number that is the equivalent binary number when each bit in the binary number is toggled. Syntax AOR(binary_number.binary_number) Category Arithmetic Runtime 3.1 and above Notes This function is not intended for general use.ANOT() Returns the arithmetic (binary) NOT of a binary number. Syntax COS(radians) Category Arithmetic Runtime 6.1 and above Notes This function is not intended for general use. Example: SET ws-num = AOR(13. Syntax ANOT(binary_number) Category Arithmetic Runtime 3.0 and above 111 . The result is in ONE’s complement based on a 32 bit number.5 v1. Syntax FRACTION(number) Category Arithmetic Runtime 3.10 co-ordinate. 10 + x-increment // // Result: The above code example will position 1 pixel down // and to the right of the @10. that is.1 and above Example: FIELD ws-num PIC 99V99 ws-fraction PIC 99V99 SET ws-num = 12.  Height of standard character in pixels. INTEGER() Returns the integer part of the number. Applications should store these values in a field if the values are used multiple times. Example: //To address an individual pixel. truncates the number so that there are no decimal places.5 and above Notes The metrics currently supported are:  Width of standard character in pixels.  Width of screen in pixels.See Also SIN().34 GET-SYSTEM-METRICS() Returns the value of the specified system metric. that is. Note: This function queries the client interface for this information. Syntax Category INTEGER(number) Arithmetic 112 .  Height of screen in pixels. returns the decimal places of the number.34 SET ws-fraction = FRACTION(ws-num) // // Result: ws-fraction = 0. the co-ordinate increment //for a pixel can be determined as follows: FIELD x-increment PIC 9V9(6) FIELD y-increment PIC 9V9(6) SET x-increment = 1 / GET-SYSTEM-METRICS(1) SET y-increment = 1 / GET-SYSTEM-METRICS(2) DISPLAY "TEST" @10 + y-increment. It is recommended that a field used to store the pixel increments is defined with a minimum of 4 decimal places. Syntax GET-SYSTEM-METRICS(metric_number) Category Arithmetic Runtime 6. TAN() FRACTION() Returns the fractional part of a number. which means that there is a communications overhead each time this function is called. The binary number is expressed in decimal. LSHIFT(binary_number. See Also RSHIFT() Example: 00000001 = Example: 00000010 LSHIFT(1.1) MESSAGE "Rshifted Num Once =" ws-a SET ws-a = RSHIFT(ws-a.3) = 8 Example: 00000001 RSHIFT(8.3) = 1 1 Example: FIELD ws-a PIC 9(8) SET ws-a = 1 MESSAGE "Original Num=" ws-a SET ws-a = LSHIFT(ws-a.Runtime 3.00 LSHIFT() Shifts the number left by the number of places and returns the decimal equivalent.1) MESSAGE "Lshifted Num Once =" ws-a SET ws-a = LSHIFT(ws-a.1) MESSAGE "Lshifted Num Twice=" ws-a SET ws-a = LSHIFT(ws-a.1) MESSAGE "Lshifted Num Thrice=" ws-a SET ws-a = RSHIFT(ws-a.1 and above See Also FRACTION() Example: FIELD ws-num PIC 99V99 ws-integer PIC 99V99 SET ws-num = 12.1) = 2 Example: 00000100 LSHIFT(1.34 SET ws-integer = INTEGER(ws-num) // // Result: ws-integer = 12.1) MESSAGE "Rshifted Num Twice=" ws-a // // Result: Original Num=1 // Lshifted Num Once =2 // Lshifted Num Twice=4 // Lshifted Num Thrice=8 // Rshifted Num Once =4 // Rshifted Num Twice=2 113 .2) = 4 Example: 00001000 LSHIFT(1.no_of_places) Syntax Category Arithmetic Runtime 3.1 and above Notes This function is not intended for general use. y) Category Arithmetic Runtime 3. Syntax MIN-VALUE(field) Category Environment Runtime 3.1 and above Notes If x is zero. If x is negative.2) MESSAGE "Deferred Rate = " ws-deferred-rate // // Result: Deferred Rate = 0.99" " MIN-VALUE() Returns the smallest possible value a field can contain. y must be an integer. Syntax MAX-VALUE(field) Category Arithmetic Runtime 3.1 and above Example: // Extract a range of records based on MIN and MAX FIELD amount PIC S9(9)V99 EXTRACT debtor-trans WHERE amount BETWEEN MIN-VALUE(amount) AND MAX-VALUE(amount) // // Result: Records for all values of amount will be extracted Example: FIELD amount PIC S9(3)V99 MESSAGE "Amount MAX Value = " MAX-VALUE(amount) MESSAGE "Amount MIN Value =" MIN-VALUE(amount) // // Result: "Amount MAX Value = 999.001600 114 . Syntax POWER-OF(x.MAX-VALUE() Returns the largest possible value a field can contain.99 " "Amount MIN Value = -999.1 and above See Also MAX-VALUE() POWER-OF() Returns the result x to the power of y ( xy ). Zero is returned when illegal x and y values are passed. y must be positive. Example: // Calculated Deferred Rate // = (( Percent Complete / 10) to the power of 2) // NB: For purposes of example only percent complete // has been set to be 40 % but would otherwise be // calculated on the fly. FIELD tmp-percent-complete PIC 9(3) ws-deferred-rate PIC 9(4)V9(6) SET tmp-percent-complete = 40 SET ws-deferred-rate = POWER-OF(((tmp-percent-complete / 100) / 10). Issuing the same seed value should result in the same set of random numbers being returned.no_of_places) Category Arithmetic Runtime 3. The seed is a number used to alter the starting point for the random numbers for the first call to RANDOM. 13911 Example 2: SET lf-seed = TOD() FOR lf-i = 1 TO 10 SET lf-seed = RANDOM(lf-seed) MESSAGE lf-seed END-FOR // RESULT: This snippet produces a continuously varying random output because // the seed varies by at least one second each time it is run. RSHIFT() Shifts the binary number right by the number of places and returns the decimal equivalent. See Also LSHIFT() SIGN-OF() Returns an integer value indicate the sign of the result of a specified expression. 115 . Syntax RANDOM(seed) Category Arithmetic Runtime 3. Syntax SIGN-OF(expression) Category Arithmetic Runtime 4.1 and above Notes This function is not intended for general use. 24317.1 and above Notes This function is not intended for general use.RANDOM() Generates a pseudo random number in the range 0 to 32767. 9625. Syntax RSHIFT(binary_number. 4499. The binary number is expressed in decimal.1 and above Notes This function returns one of the following values:  -1: If the result is a negative value. Example 1: LOCAL lf-seed TYPE NUMERIC lf-i TYPE NUMERIC // SET lf-seed = 1201 FOR lf-i = 1 TO 10 SET lf-seed = RANDOM(lf-seed) MESSAGE lf-seed END-FOR // RESULT: This snippet produces the following pseudo-random output each time it // runs: // 3960. 17461. 12970. 14730. 15372. 31469.  1: If the result is a positive value. Example: LOCAL FIELD lf-a PIC 9(2) lf-b PIC 9(2) SET lf-a = 9 SET lf-b = 12 IF SIGN-OF(lf-a . The TANGENT of an angle is the ratio of the length of the opposite side to the length of the adjacent side. TAN() Example: LOCAL lf-angle TYPE NUMERIC // expressed in radians 116 .lf-b) > 0 MESSAGE "POSITIVE result" ELSE MESSAGE "ZERO result" ENDIF // // Result: "NEGATIVE result" SIN() Returns the sine of an angle expressed in radians.5 v1.  0: If the result is zero.0 and above Notes Trigonometric functions specify the relationships between the side lengths and the interior angles of a right triangle.lf-b) < 0 MESSAGE "NEGATIVE result" ELSEIF SIGN-OF(lf-a . Syntax SIN(radians) Category Arithmetic Runtime 6. The COSINE of an angle is the ratio of the length of the adjacent side to the length of the hypotenuse. The SINE of an angle is the ratio of the length of the opposite side to the length of the hypotenuse. See Also COS(). // SET lf-angle = 70 MESSAGE "The Sine of an angle of 70 radians is " SIN(lf-angle) MESSAGE "The Cosine of an angle of 70 radians is " COS(lf-angle) // //RESULT: The Sine of an angle of 70 radians is 0.00 Next Num to use = 12. If x is negative. this function returns 0. Syntax SQUARE-ROOT(x) Category Arithmetic Runtime 3.01 // If there are no notes for ASSET1 // Note Seq: 0.00 Next Num to use = 1. 117 .1 and above Example: FIELD ws-next-seq-no LIKE asset-note-seq // asset-note-seq is defined as PIC 9(3)v99 SET asset-no = 'ASSET1' GET asset-notes LAST ON INDEX asset-no asset-note-seq KEY IS asset-no ON ERROR SET asset-note-seq = 0 SET ws-next-seq-no = 1 ELSE SET ws-next-seq-no = asset-note-seq + SMALLEST-INCREMENT(asset-note-seq) END-ON MESSAGE "Note Seq: " asset-note-seq " Next Num to use = " ws-next-seq-no // // Result: Assuming ASSET1 Note Seq 12 exists then // Note Seq: 12.0001. if the field is defined as having 4 decimal places.1 and above Notes The result is numeric. For example. Example: FIELD ws-num PIC 99 SET ws-num = 9 MESSAGE SQUARE-ROOT(ws-num) // // Result: 3. then the value returned will be 0.773891 The Cosine of an angle of 70 radians is 0.000000 STR() Returns the string representation of a number.633319 SMALLEST-INCREMENT() Returns the smallest incremental value for a field.00 SQUARE-ROOT() Returns the square root of a value. Syntax SMALLEST-INCREMENT(field) Category Arithmetic Runtime 4. SUM-ARRAY() Returns the sum (arithmetic addition) of the elements of the specified numeric array.1 and above Notes The string is left justified.1 and above Notes This function can only be used in a SELECT statement. Example: SET ws-text = STR(ws-num) SUM() Returns the sum of a numeric field. Syntax SUM-ARRAY(field_name. COS() Date Handling Functions PRONTO-RAD supports the following date handling functions: ADD-MONTH() DAY-IN-MONTH() MINUTE() DATE-FROM-DATE-TIME() DOW() MONTH() 118 . TAN(radians) Syntax Category Arithmetic Runtime 6.Syntax STR(number) Category String Runtime 3.to) Category Arithmetic Runtime 3. Example: SET sales-ytd = SUM-ARRAY(monthly-sales.1 and above Notes The elements that are summed are specified by the from and to subscript values.5 v1.MONTH(TODAY()) TAN() Returns the tangent of an angle expressed in radians. FSTR or ZSTR can be used for a more formatted result.from.1. and no decimal places are included.0 and above See Also SIN(). Syntax SUM(variable_name) Category Arithmetic Runtime 4. Example: // Select Example SELECT * FROM debtor-sales GROUP BY deb-stock-group HAVING SUM(ytd-total-cost) > 10 // // Result: The total of the records for each group must // exceed 10 before the group summary record // is displayed. Syntax Category DATE-FROM-DATE-TIME(date-time.1. in which case the day number will be set to the last day of the resultant month.end-of-month-flag) Category Date Runtime 3. and calculates and returns a date based on the following rules:  The day in the resultant date will be the same day number as in the original date unless  The day of the original month is greater than the maximum number of days in the resultant month. Example: SET ws-orig-date = 02-JAN-2000 SET ws-calc-date = ADD-MONTH(ws-orig-date. the day will be the same day number as the original date.1.1.num-months. the last day of the resultant month will be returned. .0) // // Result: ws-calc-date = 29-FEB-2000 (leap year) Example: SET ws-orig-date = 30-APR-1999 SET ws-calc-date = ADD-MONTH(ws-orig-date.  The day of the original month is the last day of the original month then .1) // // Result: now ws-calc-date = 31-MAY-1999 DATE-FROM-DATE-TIME() Returns the date part of a date-time value.0) // // Result: now ws-calc-date = 30-MAY-1999 Example: SET ws-orig-date = 30-APR-1999 SET ws-calc-date = ADD-MONTH(ws-orig-date.0) // // Result: ws-calc-date = 02-FEB-2000 Example: SET ws-orig-date = 30-JAN-2000 SET ws-calc-date = ADD-MONTH(ws-orig-date.gmt) Date 119 .If the end-of-month-flag is zero. The function handles leap years.1 and above Notes The num-months value can also be negative in order to go back a number of months. Syntax ADD-MONTH(date.DATE-TIME() HOUR() MONTH-NAME() DATE-TO-JULIAN() JULIAN() SECOND() DAY() JULIAN-TO-DATE() TIME-FROM-DATE-TIME() DAY-NAME() LEAP-YEAR() YEAR() ADD-MONTH() Adds a specified number of months to a date.If the end-of-month-flag is non-zero.1. TRUE or ‘1’) indicates that the date-time value returned will have been adjusted by the time zone difference. Likewise when the field is displayed it will always display in local time.1 and above Notes The gmt parameter. The gmt parameter. indicates that the date value returned will not be adjusted by the time zone difference.Runtime 4. It is not advisable to store these values in fields of type TIME. See Also DATE-TIME() Example: SET ws-date-time = GMT() // The entire application needs to always set this field to gmt() SET ws-date = DATE-FROM-DATE-TIME(ws-date-time. dates prior to 1970 are invalid. indicates that the date-time value returned will not be adjusted by the time zone difference. All fields (including dictionary fields) that are defined as a type ‘J’ (Date/time) are assumed to be held in gmt(). //For example: SET lf-date = 13-FEB-2005 SET lf-time = 13:10:52 //lf-date and lf-time are in local time SET lf-date-time = DATE-TIME(lf-date. however.true) // The ws-date field will hold the date in your local time.FALSE) is set. then the ws-date will be the gmt date. Syntax DATE-TIME(date.time. as the information may be lost if the field is written to an external file. The same applies to the PRINT and Message statements. These values should be stored in fields of type DATE-TIME. if zero. if non-zero (that is. As a result. Example: FIELD lf-date-time lf-date lf-date-stamp lf-time lf-time-stamp TYPE TYPE TYPE TYPE TYPE DATE-TIME DATE DATE TIME TIME //A date time stamp would normally be derived from either function sys-time() //or GMT() configured to return Universal Time (that is. TRUE or ‘1’) indicates that the date value returned will have been adjusted by the time zone difference. if non-zero (that is. The format of this date-time value is consistent with that returned by the SYSTIME() function. if zero. This means if the field is accepted directly. the date would be entered as local time. If ws-date = date-from-date-time (ws-date-time.lf-time. it will be stored as gmt. which is the number of seconds since midnight on January 1st.gmt) Category Date Runtime 4. The gmt parameter. GMT not Local Time) //It is best to have either of these return both time and date trapped //at a single instant in time that is independent of Time Zone in order to //obtain meaningful comparisons between 2 transactions recorded in two //different time zones. DATE-TIME() Returns a single value containing the date and time combined. 1970 (this is how UNIX stores times).1 and above Notes The gmt parameter.1) 120 . Example: FIELD tmp-text PIC X(20) calc-date TYPE DATE SET tmp-text = "02 03 1990" SET calc-date = DATE2JULIAN(tmp-text) // // Result: calc-date = 02-MAR-1990 Example: SET tmp-text = "JAN 04 1992" SET calc-date = DATE2JULIAN(tmp-text) // // Result: calc-date = 04-JAN-1992 Example: SET tmp-text = "06 SEP 1999" SET calc-date = DATE2JULIAN(tmp-text) // // Result: calc-date = 06-SEP-1999 DAY() Returns the day of the month for the specified date.1) MESSAGE "Date: " lf-date-stamp // SET lf-time-stamp = TIME-FROM-DATE-TIME(lf-date-time. MESSAGE "Date/Time = " lf-date-time // SET lf-date-stamp = DATE-FROM-DATE-TIME(lf-date-time. Syntax DAY(date) Category Date Runtime 3. jan 1 87).1 and above Notes This function interprets the text passed and determines whether DAY or MTH was passed first. Syntax DATE-TO-JULIAN(free-format-date-as-text) DATE2JULIAN(free-format-date-as-text) Category Date Runtime 3. accept.//lf-date-time is physically stored as gmt //Any display. YEAR is expected to be in the LAST position.1) MESSAGE "Time: " lf-time-stamp // // Result: Date/Time = 13-FEB-2005 13:10:52 // Date: 13-FEB-2005 // Time: 13:10:52 DATE-TO-JULIAN() Returns the date in julian form of an alphanumeric or string field containing a text representation of a date (for example.1 and above Example: FIELD ws-day-no PIC 99 SET gl-trans-date = 3-FEB-2000 SET ws-day-no = DAY(gl-trans-date) 121 . print or MESSAGE statements (of fields declared as //type date-time) will automatically be adjusted by the time zone //difference and will show local date/time. Syntax DAY-NAME(date) Category Date Runtime 3.7) 122 .1 and above Notes Month numbers should be between 1 and 12. Friday) of the specified date.year) Category Date Runtime 3. 7=SAT. Example: FIELD ws-date TYPE DATE ws-last-fridays-date TYPE DATE //(that is. The year value must be specified but is only used when determining the number of days in February. 3=TUE. irrespective of ACTUAL date) SET ws-date = TODAY() SET ws-last-fridays-date = ((ws-date . 4=WED.ws-year) // // Result: ws-days-in-mth = 29 DOW() Returns a day of week number (1-7) for a specified date Syntax DOW(date) Category Date Runtime 3. 6=FRI. 2=MON.1 and above Example: FIELD ws-day-name PIC X(10) SET gl-trans-date = 4-FEB-2000 SET ws-day-name = DAY-NAME(gl-trans-date) // // Result: ws-day-name = "Friday" DAYS-IN-MONTH() Returns the number of days in the specified month.// // Result: ws-day-no = 3 DAY-NAME() Returns the day name (for example. Syntax DAYS-IN-MONTH(month. 5=THU.DOW(ws-date) + 6) .1 and above Notes The return values are 1=SUN. This function is useful for adding a specific numbers of days to a date and maintaining the SAME DAY NAME across month boundaries. PRONTO-Xi application programmers can make use of definitions for the weekday names found in include stddef. Example: FIELD ws-mth PIC 99 ws-year PIC 9(4) ws-days-in-mth PIC 99 SET gl-trans-date = 4-FEB-2000 SET ws-mth = MONTH(gl-trans-date) SET ws-year = YEAR(gl-trans-date) SET ws-days-in-mth = DAYS-IN-MONTH(ws-mth. 1 and above See Also MINUTE().ws-mth. month and year values. for example.MESSAGE "Last Friday's Date was " ws-last-fridays-date "Day: " DAY-NAME(ws-last-fridays-date) "DOW: " DOW(ws-last-fridays-date) HOUR() Returns the hour number from the specified time value. It is 123 . Example: FIELD ws-date TYPE DATE ws-day PIC 99 ws-mth PIC 99 ws-year PIC 9(4) SET ws-day = 5 SET ws-mth = 2 SET ws-year = YEAR(TODAY()) SET ws-date = JULIAN(ws-day. Syntax JULIAN-TO-DATE(date) JULIAN2DATE(date) Category String Runtime 3.mm. since PRONTO-Xi automatically formats a date field into a string representation in these situations. 12-JAN1991. SECOND() Example: LOCAL FIELD lf-time TYPE TIME SET lf-time = TOD() MESSAGE "Time of Day function captured " lf-time " .HH: 17 // MM: 24 // SS: 37 JULIAN() Returns a date in julian format for the specified day.yy) Category Date Runtime 3.1 and above Notes This function is especially useful in system interface and data conversion programs.1 and above Notes There is no need to use this function to print or display a date.ws-year) // // Result: Assuming the year 2000. Syntax JULIAN(dd. ws-date will be 05-FEB-2000 JULIAN-TO-DATE() Converts the specified date into an alphanumeric string of the form dd-mmm-yyyy. Syntax HOUR(time) Category Date Runtime 4.HH: " HOUR(lf-time) " MM: " MINUTE(lf-time) " SS: " SECONDS(lf-time) // Result: Time of Day function captured 17:24:37 // . JULIAN-TO-DATE(TODAY())) MESSAGE tmp-mail-text // // Result: Sent to Customer: LAYLA By eric On 21-FEB-2000 LEAP-YEAR() Returns a True/False result indicating whether a specified year is a leap year.HH: 17 // MM: 24 // SS: 37 MONTH() Returns the month number (1-12) of the specified date. Syntax MINUTE(time) Category Date Runtime 4.HH: " HOUR(lf-time) " MM: " MINUTE(lf-time) " SS: " SECONDS(lf-time) // // Result: Time of Day function captured 17:24:37 // . Example: IF LEAP-YEAR(YEAR(02-FEB-2000)) MESSAGE "The Year 2000 is a Leap Year" ENDIF // // Result: The Year 2000 is a Leap Year MINUTE() Returns the minute number from the specified time value. otherwise FALSE (0). LOGIN-ID() ." By ".accountcode . Syntax LEAP-YEAR(year) Category Date Runtime 3. Syntax Category MONTH(date) Date 124 . login = 'eric'. Example: // Construction of a line of mail text for audit purposes // Assume accountcode = 'LAYLA'. and today is 21-FEB-2000 FIELD tmp-mail-text PIC X(70) SET tmp-mail-text = CONCAT("Sent to Customer: ".mainly useful when there is a need to perform some string operation on the representation of the date.1 and above Notes This function returns TRUE (1) for a leap year. SECOND() Example: LOCAL FIELD lf-time TYPE TIME SET lf-time = TOD() MESSAGE "Time of Day function captured " lf-time " .1 and above See Also HOUR()." On ". January) of the specified date.1 and above Example: SET ws-period-date = 31-JAN-1998 PRINT "Transaction Report for " IN COL 10 MONTH-NAME(ws-period-date) // // Result: prints "Transaction Report for January" SECOND() Returns the second component of a specified time value. indicates 125 . if zero.Runtime 3.HH: 17 // MM: 24 // SS: 37 TIME-FROM-DATE-TIME() Returns the time component of a date-time value. if non-zero (that is. Syntax MONTH-NAME(date) Category Date Runtime 3. MINUTE() Example: LOCAL FIELD lf-time TYPE TIME SET lf-time = TOD() MESSAGE "Time of Day function captured " lf-time " .gmt) Category Date Runtime 4. Syntax SECOND(time) Category Date Runtime 4. The gmt parameter.1 and above Notes The gmt parameter.1 and above Example: FIELD ws-mth-no PIC 99 SET gl-trans-date = 3-FEB-2000 SET ws-mth-no = MONTH(gl-trans-date) // // Result: ws-mth-no = 2 MONTH-NAME() Returns the month name (for example.HH: " HOUR(lf-time) " MM: " MINUTE(lf-time) " SS: " SECONDS(lf-time) // // Result: Time of Day function captured 17:24:37 // . Syntax TIME-FROM-DATE-TIME(date-time. TRUE or ‘1’) indicates that the time value returned will have been adjusted by the time zone difference.1 and above See Also HOUR(). All fields (including dictionary fields) that are defined as a type ‘J’ (Date/time) are assumed to be held in gmt(). then the ws-time will be the gmt time. Likewise when the field is displayed it will always display in local time. however. YEAR() Returns the year number of the specified date. it will be stored as gmt. The same applies to the PRINT and MESSAGE statements.FALSE) is set.1 and above Example: FIELD ws-year-no PIC 9(4) SET gl-trans-date = 3-FEB-2000 SET ws-year-no = YEAR(gl-trans-date) // // Result: ws-year-no = 2000 Environment Functions PRONTO-RAD supports the following environment functions: ACTIVE-PID() GMT() OLE-QUERY-INTERFACE() BATCHED() GRANT-DB-SCHEMA() OLE-RELEASE() CAN-DDE() IF-THEN-ELSE() OLE-STATUS() CD() IS-A-DIR() OLE-UNADVISE-EVENT() CD-WITHOUT-CLOSE-ALL() LOCAL-CD() OLE-UNADVISE-ALL() CHECK-AUTH() LOCAL-CD-WITHOUT-CLOSEALL() OPERATING-SYSTEM() COLOUR-PICKER() LOCAL-DIR() PAGE-NO() CREATE-DB-SCHEMA() LOCAL-NO() PARAM-CNT() CREATE-DB-USER() LOGIN-ID() PID() CURRENCY-SIGN() MAIL-ADD-LINE() PRONTO-RELEASE() DATABASE-TYPE() MAIL-ATTACH() PROUSER-FLAGS() DB-COMMAND() MAIL-CANCEL() REFRESH-QUICK-LINKS() DB-TABLE-NAME() MAIL-FROM-NAME() REPORT-IS-XML() DDE-ERROR-STATUS() MAIL-REPLY-TO() REVIEW-ROW() DDE-EXECUTE() MAIL-START() REVOKE-DB-SCHEMA() 126 . the date/time would be entered as local time.true) // //Result: The ws-time field will hold the time in your local time. See Also DATE-TIME() Example: SET ws-date-time = GMT() // The entire application needs to always set this field to gmt() SET ws-time = TIME-FROM-DATE-TIME(ws-date-time. This means if the field is accepted directly. Syntax YEAR(date) Category Date Runtime 3. If ws-time = time-from-date-time (ws-date-time.that the time value returned will not be adjusted by the time zone difference. It returns TRUE (non-zero) if there is an active process on the machine with the specified 127 .1 and above Notes This function is not intended for general use.DDE-INITIATE() MAIL-SEND() RGB-TO-COLOUR() DDE-POKE() MAX-SCREEN-COLUMNS() RMDIR() DDE-REQUEST() MAX-SCREEN-ROWS() SCREEN-MODE() DDE-TERMINATE() MESSAGE-STATUS() SEARCH() DELETE-REGISTRY-VALUE() MKDIR() SEARCH-MODE() DIARY() MODE-NAME() SECURITY-LEVEL() DIR() MODIFICATION-TIME() SET-DATA-AREA-NAME() ENABLE-SYSTEM-MENU() MOUSE-COLUMN() SET-BACKGROUND-IMAGE() ENABLE-STATUS-BAR() MOUSE-ROW() SET-ENVIRONMENT() ENABLE-TOOL-BAR() NEXT-DIR-ENTRY() SET-FUNCTION-CODE() ERROR-DESCRIPTION() NODE-NAME() SET-HELP-CONTEXT() ESCAPE() OLE-ADDREF() SET-MODULE-CODE() EXIT-STATUS() OLE-ADVISE-EVENT() SET-REGISTRY-VALUE() FILE-EXISTS() OLE-BULK-PUT() SLEEP() FILE-NAME() OLE-CALL-INTERACTIVEMETHOD() SPOOL-FILE-NAME() FILE-OWNER() OLE-CALL-METHOD() START-DIR-SEARCH() FILE-STATUS() OLE-CREATE-CONTROL() SYSTIME() FILE-VERSION() OLE-CREATE-INSTANCE() TIME-ELAPSED() FINISH-DIR-SEARCH() OLE-ENUM-NEXT() TIME-ZONE() GET-ENV() OLE-ENUM-RESET() TOD() GET-FIELD-VALUE() OLE-ERROR-DESCRIPTION() TODAY() GET-FIELD-VALUENUMERIC() OLE-GET-ACTIVE-OBJECT() TRANSACTION-ACTIVE() GET-PARAM() OLE-GET-DISPATCH-ID() TTY() GET-REGISTRY-ENUM-KEY() OLE-GET-EVENT() UID() GET-REGISTRY-ENUMVALUE() OLE-GET-PROPERTY() USER-GROUP() GET-REGISTRY-VALUE() OLE-PUT-PROPERTY() VALID-ACTIVATION-KEY() GID() OLE-PUT-PROPERTY-BYREF() WAIT-FOR-INPUT() ACTIVE-PID() Returns a True/False result indicating whether an active process with the specified process ID is running on the current machine. Syntax ACTIVE-PID(pid-number) Category Environment Runtime 4. and is applicable to UNIX implementations only. Syntax CAN-DDE() Category Environment Runtime 5. etc. Example: FIELD ws-id PIC S9(4) ws-result PIC S9(8)V99 PROCEDURE main IF NOT CAN-DDE() MESSAGE "DDE functions will not run in this environment" ELSE SET ws-id = DDE-INITIATE("Excel".1 and above Notes This function returns TRUE (non-zero) if the program is running in the PRONTO-Xi batch queue.process ID. otherwise it returns FALSE (zero). "Sheet1") IF ws-id <= 0 128 . Syntax BATCHED() Category Environment Runtime 3. otherwise returns FALSE (zero) if DDE functions are not available. The use of DDE is actively discouraged as connection to third-party software applications and COM objects can be made using PRONTO-Xi OLE statements and functions.) The PID() function must be used first to determine the process-id to query. DDE facilities are no longer supported by Microsoft and little or no documentation exists on DDE requests. Example: SET ws-process-id = PID() IF ACTIVE-PID(ws-process-id) //command-statements ENDIF BATCHED() Returns a True/False result indicating whether the program is running in the PRONTO-Xi batch queue. Visual Basic calls to Microsoft applications can sometimes be similar in construct to DDE requests. see the include ‘rbtchproc’.0 and above Notes This function returns TRUE (non-zero) if the current environment can perform DDE functions. batch daemon. It can be used to determine whether a UNIX process is still active (for example. For example. This function is mainly for use with the Windows operating system. Example: IF BATCHED() DO some-processing-in-background ELSE DO ask-first-then-process-file ENDIF CAN-DDE() Returns a True/False result indicating whether DDE functions can be performed in the current environment. otherwise it returns FALSE (zero). PRONTO-Xi applications can use alternative methods to determine if a program is batched. print job. Syntax CD-WITHOUT-CLOSE-ALL(dir-path) Category Environment Runtime 4. Syntax CD(dir-path) Category Environment Runtime 3. otherwise FALSE (zero). as it may not be obvious what directories files are open in.please start Excel first.1 and above Notes This function returns TRUE (non-zero) if successful. LOCAL-CD-WITHOUT-CLOSE-ALL() CHECK-AUTH() Returns a True/False result indicating whether a specified product is licensed for use on the current machine. "124") MESSAGE "poke error" ELSE SET ws-result = NUM(DDE-REQUEST(ws-id.1 and above Notes This function is equivalent to the CD() function. When the current working directory is changed with the CD function. Previously any file that was open prior to the CD and remained open after the CD would still refer to the file in the previous directory and not the current directory. This was considered to be far too error prone to be the default case."R1C1")) IF SLEEP(5) ENDIF MESSAGE "r1c1 is set to " ws-result IF DDE-TERMINATE(ws-id) ENDIF MESSAGE "Finished" ENDIF ENDIF ENDIF //Result: "r1c1 is set to 124. LOCAL-CD-WITHOUT-CLOSE-ALL() Example: IF CD(GET-ENV("TMPDIR")) MESSAGE "Successfully changed to directory " GET-ENV("TMPDIR") ENDIF CD-WITHOUT-CLOSE-ALL() Attempts to change the current working directory to the specified directory path and returns a True/False result indicating the success of the operation. except it does not perform a CLOSE ALL. all data files currently open are automatically closed. See Also CD-WITHOUT-CLOSE-ALL(). See Also CD(). 129 . then re-run this program" ELSE IF NOT DDE-POKE(ws-id. It should be used with extreme caution. LOCAL-CD().00" (assuming one can-dde) CD() Attempts to change the current working directory to the specified directory path and returns a True/False result indicating the success of the operation. LOCAL-CD(). "r1c1". The CD() function performs an automatic CLOSE ALL.MESSAGE "Initiation Error . This function returns ZERO if successful.90 COLOUR IS lf-fgcolour ON lf-fgcolour ABSOLUTE-COORDINATES ACCEPT lf-sample @3. Example: IF NOT CHECK-AUTH(product-id-number) MESSAGE "No access to this Product/Module" ENDIF COLOUR-PICKER() Displays a standard colour picker dialog box and returns the value of the selected colour (in internal PRONTO-Xi colour format). 130 . system administration type program. otherwise it returns FALSE (zero). It returns TRUE (non-zero) if the product is licensed.0 and above Notes This function is not intended for general use.5 Example: // //This program displays screen colours selected using the Colour Picker Function. otherwise it returns the failure error number. STR(lf-fgcolour)) REFRESH lf-sample END-ON END-SCREEN //show-colours CREATE-DB-SCHEMA() Attempts to create a PRONTO-Xi schema (data area) of the specified name in the RDBMS. // SCREEN show-colours WINDOW LOCAL lf-sample PIC X(30) lf-fgcolour TYPE COLOUR ALLOWED ENTRY BEFORE SET lf-sample = "Press F2 to choose a colour" SET lf-fgcolour = RED DETAIL BOX @1. It may be useful for a high security level.4 v0. Syntax COLOUR-PICKER(default-colour-value) Category Environment Runtime 6.5 COLOUR IS lf-fgcolour DEFAULT lf-sample ON HELP-KEY SET lf-fgcolour = COLOUR-PICKER(lf-fgcolour) SET lf-sample = CONCAT("Sample Colour Number: ".Syntax CHECK-AUTH(product-id-number) Category Environment Runtime 4.1 TO @20.1 and above Notes This function is not intended for general use. Syntax CREATE-DB-SCHEMA(schema-name.SPACES) Category Environment Runtime 5. 1 and above Notes The runtime currency symbol is maintained via PROADMIN > Miscellaneous > PRONTOXi System Parameters Example: PRINT CURRENCY-SIGN() IN COL 10 // // Result: For example.SPACES) IF ws-status != 0 MESSAGE "create-db-user error ". Syntax DATABASE-TYPE() Category Environment Runtime 4. The second parameter is reserved for future use and should be passed as SPACES. GRANT-DB-SCHEMA(). Only relevant to RDBMS systems. It may be useful for a high security level. Syntax CREATE-DB-USER(username. DATABASE-TYPE() Returns the name of the type of database being used.1 and above 131 . or the name of the required schema. REVOKE-DB-SCHEMA() Example: SET ws-status = CREATE-DB-SCHEMA(new-schema-name.0 and above Notes This function is not intended for general use. The required privilege must be within the RDBMS to create a user.SPACES) IF ws-status != 0 MESSAGE "create-db-schema error ". The required privilege must be within the RDBMS to create a schema. $). ws-status ENDIF CURRENCY-SIGN() Returns the character defined as the currency sign (for example. Syntax CURRENCY-SIGN() Category String Runtime 4. See Also CREATE-DB-USER(). and returns ZERO if successful. The second parameter is reserved for future use and should be passed as SPACES. system administration type program.SPACES) Category Environment Runtime 5. will print $ if that is the PRONTO runtime // currency symbol. GRANT-DB-SCHEMA(). See Also CREATE-DB-SCHEMA(). ws-status ENDIF CREATE-DB-USER() Attempts to create a PRONTO-Xi user of the specified name in the RDBMW. otherwise it returns the failure error number. Only relevant on RDBMS systems.The first parameter can be specified as the directory path to the data area to be associated with the schema. REVOKE-DB-SCHEMA() Example: SET ws-status = CREATE-DB-USER(new-user-name. Only database commands that do not produce output can be issued (for example. Syntax DB-TABLE-NAME(object) Category Environment Runtime 4. Refer to manual for the relevant database command. Example: 132 . Example: SET lf-return-status = DB-COMMAND("TEXT OF DATABASE-SPECIFIC COMMAND") DB-TABLE-NAME() Returns the actual table name for the object. It would mainly be used in debugging or resolving relational database issues. A -1 value will be returned if this is not a relational database version of PRONTO-RAD. The following database types are currently supported:  C-ISAM (isam)  ORACLE (relational)  SQL-SERVER (relational)  INFORMIX (relational) Example: LOCAL lf-database-type PIC X(30) // SET lf-database-type = DATABASE-TYPE() // IF lf-database-type IN { "SQL-SERVER" "ORACLE" "INFORMIX" } MESSAGE "This instance of PRONTO-Xi is using a Relational Database : " lf-database-type ELSEIF DATABASE-TYPE() = "C-ISAM" MESSAGE "This instance of PRONTO-Xi is using an ISAM Database : " lf-database-type ELSE MESSAGE "This instance of PRONTO-Xi is using : " lf-database-type ENDIF DB-COMMAND() Performs the specified database command and returns the database return status from the command that was executed.Notes PRONTO-Xi currently supports two styles of database: Relational and ISAM (an older technology which will gradually be phased out). If the table is not stored in a relational database. It does not include the file version character (if any). you cannot perform a SELECT command). Syntax DB-COMMAND(text) Category Environment Runtime 4. then spaces are returned. if stored in a relational database. It could be used to provide automation of certain database administration tasks.1 and above Notes This function is not intended for general use. Zero indicates success. and a non-zero value indicates failure.1 and above Notes This function is not intended for general use. Syntax DDE-ERROR-STATUS(conversation-id) Category DDE Runtime 5. 133 .command) Syntax Category DDE Runtime 5.0 and above See Also CAN-DDE() DDE-INITIATE() Initiates a DDE connection to the specified DDE service passing the required topic.alpha-data) Category DDE Runtime 5.topic) Category DDE Runtime 5.0 and above Notes If successful the function returns a DDE conversation ID number (non-zero). DDE-EXECUTE(conversation-id.0 and above Notes This function returns TRUE (non-zero) if successful and FALSE (zero) if not successful.item-name. Syntax DDE-POKE(conversation-id. This returns TRUE if successful and FALSE if not successful. See Also CAN-DDE() DDE-REQUEST() Attempts to request (get) the current value of a specified item within the DDE service and returns an alphanumeric value or spaces if not successful.SET lf-name = DB-TABLE-NAME(deb-master) MESSAGE lf-name // // Result: DEB5MF DDE-ERROR-STATUS() Returns the Windows DDE error status number for the last failed DDE operation for the specified conversation. Multiple DDE connections are permitted.0 and above See Also CAN-DDE() DDE-EXECUTE() Executes the specified command on the DDE service. If a connection is not established then zero is returned. Syntax DDE-INITIATE(service. This number must be passed to other DDE functions to identify the conversation. See Also CAN-DDE() DDE-POKE() Attempts to poke (set) the specified item within the DDE service with the data specified and returns a True/False result indicating the success of the operation. DIR() Returns the full path-name of the current working directory. Syntax DIR() Category Environment Runtime 3.1 and above Notes The PRODIARY facility is obsolete. If the key ends with a slash (/ or \) it is assumed that the default value for the key is to be deleted. SET-REGISTRY-VALUE DIARY() Returns a True/False result indicating whether the current user has a PRODIARY entry for today. See Also GET-REGISTRY-VALUE.0 and above Notes The return value of this function should be ignored. otherwise returns FALSE (zero). otherwise FALSE (non-zero). Syntax DELETE-REGISTRY-VALUE(registry-key) Category Environment Runtime 6. IS-A-DIR() Example: FIELD ws-dir PIC X(80) SET ws-dir-name = DIR() 134 . See Also CAN-DDE() DELETE-REGISTRY-VALUE() Attempts to delete the specified Windows registry value associated with the registry key.0 and above See Also CAN-DDE() DDE-TERMINATE() Terminates (ends) a DDE conversation.Syntax DDE-REQUEST(conversation-id.1 and above See Also FILE-EXISTS().4 and above Notes This function returns TRUE (non-zero) if successful.item-name) Category DDE Runtime 5. Syntax DDE-TERMINATE(conversation-id) Category DDE Runtime 5. This function returns TRUE (non-zero) if the user has any diary entries for today. Syntax DIARY() Category Environment Runtime 3. 3 and above Notes This function is not intended for general use.15 DISPLAY "and persist certain enabled attributes of a called child program" @5. Edit. Tools and Help options can be hidden with the ENABLE-SYSTEM-MENU function. View. In UNIX type systems. so the last request alway persists. the reason for disabling (and later re-enabling) these menu options is to permit access to the entire screen space of a terminal.  ProClient has the File->Settings option to control the display of the status bar and toolbar. ENABLE-STATUS-BAR() Example: // Program: $CUS/CallEnable. In general. See Also ENABLE-TOOL-BAR(). maximised or not) of the program window that set it. // SCREEN main LOCAL lf-j PIC X ALLOW ENTRY NO-OK-CANCEL BEFORE DISPLAY "PARENT PROGRAM . Syntax ENABLE-SYSTEM-MENU(boolean-value) Category Environment Runtime 6. The function shows the menu bar if the parameter is non-zero (TRUE) and removes the menu bar if zero (FALSE). The effect is not persistent between program executions on MS Windows. In this case. For further information on the PRONTO-Xi desktop refer to the Desktop-Xi manual.  By default. though it can persist for all windows and containers once an executing program has disabled it. use 'window-position -1' clause).ENABLE-SYSTEM-MENU() Use this function to enable/disable options in the main system menu (menu bar) at the top of the screen. Notes:  There are differences between UNIX and MS Windows implementations.spl // // Run each of these programs separately to see the effects of enable/disable. That is.15 PROMPT DETAIL ACCEPT lf-j @12. Certain effects of the enable functions will change dependant on the following:  The operating system  The window state (that is.  The state of the container that called this program for which the effects are being set. the window must be maximised (to occupy the full screen. All requests to control these attributes are considered equal. the effect will persist between runs of programs within the same ProClient session. These functions do change the ProClient settings. a maximised PRONTO-Xi window has no status bar. The effect of disabling/re-enabling the menu bar is only immediate within a program whose window has been defined to occupy the full screen.Shows how PRONTO Windows will inherit " @3.35 UPPERCASE ALLOW YES NO DEFAULT YES TITLE "Run Child Program:" 135 . the standard Windows menu bar at the top of the PRONTO-Xi desktop including the File. 15 PROMPT EXIT ENDIF END-CONFIRM END-SCREEN // End of program $CUS/CallEnable.(Persists between runs)" 'D' TITLE "Tool Bar ON" 'E' TITLE "System Menu OFF . 136 .5 DETAIL RADIO-BUTTON lf-switch @16.5 'A' TITLE "Status Bar OFF .spl ENABLE-STATUS-BAR() Enables/disables the status bar at the bottom of the PRONTO-Xi desktop. this help text will be visible at bottom of this screen" CONFIRM AUTO SPL STR-CONCAT(GET-ENV("CUS").spl SCREEN main LOCAL lf-switch PIC X WINDOW-POSITION -1 FORM-ENTRY ALLOW ENTRY NO-OK-CANCEL BEFORE DISPLAY "CHILD Program .(NB: Maximised window has no status bar by default)" @3. but NOT MS-Windows)" 'F' TITLE "System Menu ON" DEFAULT lf-switch HELP "See this on the status bar" END-RADIO-BUTTON SWITCH lf-switch CASE 'A' IF ENABLE-STATUS-BAR(false) ENDIF CASE 'B' IF ENABLE-STATUS-BAR(true) ENDIF CASE 'C' IF ENABLE-TOOL-BAR(false) ENDIF CASE 'D' IF ENABLE-TOOL-BAR(true) ENDIF CASE 'E' IF ENABLE-SYSTEM-MENU(false) ENDIF CASE 'F' IF ENABLE-SYSTEM-MENU(true) ENDIF END-SWITCH END-SCREEN //main // End of program $CUS/CanEnable.HELP "If STATUS-BAR is enabled. The function enables the status bar if a non-zero (TRUE) value is passed and disables it if the value zero (FALSE) is passed.spl // --------------------------------------------------// Program: $CUS/CanEnable.(Persists between runs on UNIX.op6") IF lf-j = NO DISPLAY "Run this program again to see effect of child program" @5."/CanEnable.(Persists between runs)" 'B' TITLE "Status Bar ON" 'C' TITLE "Tool Bar OFF . For further information on the PRONTO-Xi desktop refer to the Desktop-Xi manual. Disabling / re-enabling both the status bar and toolbar has an immediate effect within the program that makes these calls. Their effect is both global and persistent between runs of the program. Syntax ERROR-DESCRIPTION(error-number) Category Environment Runtime 4. For further information on error numbers refer to the ‘Database Error Numbers’ section.Record not found" ESCAPE() Returns a True/False result indicating whether the user backed out of the last screen displayed.Syntax ENABLE-STATUS-BAR(boolean-value) Category Environment Runtime 6. See Also FILE-STATUS() Example: // Assuming a C-ISAM environment GET job-cost-master ON INDEX job-code KEY IS 'NORECORD' // ie. The function enables the PRONTO-Xi toolbar if a non-zero (TRUE) value is passed and disables it if the value zero (FALSE) is passed. ENABLE-STATUS-BAR() ERROR-DESCRIPTION() Returns a description of the error with the specified error number. Guaranteed not to be there ON ERROR MESSAGE ERROR-DESCRIPTION(FILE-STATUS()) END-ON // // Result: messages "C-ISAM error 111 . Care should be exercised as the effects will be noticeable in other PRONTOXi windows.3 and above Notes This function is not intended for general use.1 and above Notes The FILE-STATUS() function can be used to determine the error number of a failed I/O operation. Syntax ENABLE-TOOL-BAR(boolean-value) Category Environment Runtime 6. 137 . ENABLE-TOOL-BAR() ENABLE-TOOL-BAR() Enables/disables the main PRONTO-Xi toolbar.5 and above Notes This function is not intended for general use. See Also ENABLE-SYSTEM-MENU(). Their effect is both global and persistent between runs of the program. See Also ENABLE-SYSTEM-MENU(). Care should be exercised as the effects will be noticeable in other PRONTOXi windows. For further information on the PRONTO-Xi toolbar refer to the Desktop-Xi manual. Disabling / re-enabling both the status bar and toolbar has an immediate effect within the program that makes these calls. 5 CONFIRM CONFIRMED IF SCREEN-MODE() = ENTRY SET lr-ok = TRUE ENDIF END-CONFIRM END-SCREEN EXIT-STATUS() Returns the exit status of the last routine performed.Syntax ESCAPE() Category Environment Runtime 3. Example: //If no other screens contained in initial screen SET lf-ok = FALSE WHILE NOT lf-ok DO ask-series-of-questions-screen IF ESCAPE() MESSAGE "You must complete ALL questions on the screen" ELSE BREAK ENDIF END-WHILE Example: // Recommended method(when OTHER screens exist inside // the initial screen) SET lf-ok = FALSE WHILE NOT lf-ok DO ask-series-of-questions-screen ONCE RETURNING lf-ok IF NOT lf-ok MESSAGE "You must complete ALL questions on the screen" ELSE BREAK ENDIF END-WHILE SCREEN ask-series-of-questions RETURN lr-ok TYPE BOOLEAN ALLOWED ENTRY BEFORE SET lr-ok = FALSE DETAIL ACCEPT ws-question-1 @5. The recommended/preferred method is to set a flag on displaying the screen (see example below). It returns TRUE (non-zero) if the user backed out of the last screen. Syntax EXIT-STATUS() 138 .1 and above Notes This function is not intended for general use and the results cannot be relied on in all circumstances. The return value is only correct if there are no other screens below the screen being checked. otherwise FALSE (zero).5 ON HELP-KEY DO help-for-question-1 END-ON ACCEPT ws-question-2 @6. 2 or later for this function to detect directories on the local machine (workstation). ESCAPE() Example: // Without using exit-status() (preferred method) LOCAL FIELD lf-ok TYPE BOOLEAN DO get-and-lock-debtor RETURNING lf-ok IF lf-ok DO other-processing ENDIF .Category Environment Runtime 4. Syntax FILE-EXISTS(file-name.  -3 (EXIT_PROGRAM_NOT_FOUND) Program not found. PROCEDURE get-and-lock-debtor RETURN lr-ok TYPE BOOLEAN GET deb-master lock ON ERROR SET lr-ok = FALSE ELSE SET lr-ok = TRUE END-ON Example: //Using exit-status() (NON-preferred method) DO get-and-lock-debtor IF NOT EXIT-STATUS() DO other-processing ENDIF PROCEDURE get-and-lock-debtor GET deb-master LOCK ON ERROR EXIT(1) ELSE EXIT(0) END-ON FILE-EXISTS() Indicates whether the specified file/directory exists. This function will return ‘2’ if the path passed is a directory. and corresponding constants defined by the pre-processor.7v0. ‘1’ for a file and ‘0’ if the path does not exist. The exit status of the initial routine of an external 4GL program invoked with the CALL/SPL statement will also be maintained when control is passed back to the calling program.1 and above Notes The EXIT statement can specify after it an expression to evaluate the exit status number for this routine. Note: UNIX/Linux implementations require PRONTO-Xi Thin Client release 6.on-PC-flag) 139 .  -1 (EXIT_WITH_NO_VALUE) Routine terminated by an EXIT statement without a value specified.. are: See Also  0 (EXIT_NORMAL) Routine terminated normally. The exit status of a program must be between 0 and 255..  -2 (EXIT_PROGRAM_ABORTED) External program aborted abnormally. The default exit statuses. proclient) is running. otherwise it will look on the machine where the PRONTO-Xi Client (that is.0) SET ws-wflow-program = STR-CONCAT(GET-ENV("POHMDIR")."/workflow") ELSE SET ws-wflow-program = "workflow" // Use PROPATH to find it. as Windows does not have a file owner concept.4 and above Notes Only available for UNIX/Linux. When the file does not exist or any error was encountered. See Also FILE-VERSION() Example: MESSAGE FILE-NAME(gl-master) // // Result: "$SYSGLDATA/GEN5MF" FILE-OWNER() Returns the name of the owner of the specified file.spi m6update.tec . This parameter is ignored if the application is running in a Windows environment. See Also IS-A-DIR(). Example: Data visible in UNIX Shell -r--r--r--rw-rw-r--r--r--r--rw-rw-r-- 1 1 1 1 ted mickey ned carol pronto pronto pronto pronto 1052752 1128840 331422 581 Sep Apr Aug Dec EXAMPLE: LOCAL lf-owner PIC X(30) TYPE STRING lf-file PIC X(90) TYPE STRING 140 10 13 26 14 23:33 YYYY 17:08 YYYY m6update.6 v0. Syntax FILE-OWNER(filename) Category Environment Runtime 6. is not returned. since the front-end and application run on the same machine.Category Environment Runtime 5.op6 m6update."/workflow"). The file version character.0 and above Notes The on-PC-flag parameter indicates where PRONTO-Xi should look for the file.1 and above Notes Uses the current PRONTO-Xi dictionary. ENDIF FILE-NAME() Returns the physical file name currently associated with the specified object. If set to zero (0) then PRONTO-Xi will look on the machine where the application is running. DIR() Example: IF FILE-EXISTS(STR-CONCAT(GET-ENV("POHMDIR"). Syntax FILE-NAME(object) Category Environment Runtime 4. then spaces will be returned. if present.spl m6update. Windows relies on security access lists. Spaces will be returned for this function if invoked on a Windows implementation. "K" FINISH-DIR-SEARCH() For details on this function call and example usage. Syntax FILE-VERSION(object) Category Environment Runtime 4. Syntax FILE-STATUS() Category Environment Runtime 3. refer to the ‘START-DIR-SEARCH()’ section. A zero value indicates that the operation was successful. Syntax FINISH-DIR-SEARCH() Category Environment Runtime 3.spi is owned by mickey FILE-STATUS() Returns the status of the last file operation performed. For error numbers and descriptions see the ERROR-DESCRIPTION() function."/po/m6update.1 and above Notes Uses the current PRONTO-Xi dictionary.spi") SET lf-owner = FILE-OWNER(lf-file) MESSAGE STR-CONCAT(lf-file) " is owned by " lf-owner //Result: /pluto/disneychannel/bms/po/m6update.1 and above 141 .// SET lf-file = STR-CONCAT(GET-ENV("BMS"). See Also FILE-NAME() Example: MESSAGE FILE-VERSION(deb-master) // // Result: eg.1 and above Notes PRONTO-Xi itself defines a variety of error number definition macros. See Also ERROR-DESCRIPTION() Example: GET service-engineer-master LOCK ON INDEX engineer-no KEY IS engineer-no ON ERROR IF FILE-STATUS() = ELOCKED // if another process/program has it locked MESSAGE "Cannot lock record for Engineer" engineer-no ENDIF ELSE DO maintain-engineer END-ON FILE-VERSION() Returns the file version character for the object.  Base type of the field (numeric or string) may be obtained from the dictionary to determine which function to use. Syntax GET-ENV(name) Category Environment Runtime 3. Note that the field name here is considered data. in order for the GET-FIELD-VALUE to return values correctly.4 and above See Also GET-FIELD-VALUE-NUMERIC() Notes The GET-FIELD-VALUE function requires some preparation before it can be used. Two methods can be used to reference all fields on a record simultaneously:  if 1 = 0 insert deb-master endif (sets references to all fields but never inserts)  parameter deb-master. You must also have referenced the field required (that is. If no subscript is passed.* Example: SCREEN main ALLOWED ENTRY LOCAL lf-name (all fields passed in a parameter to a procedure) PIC X(40) 142 . Referencing A Field It is not enough to only have currency on a record. NEXT-DIR-ENTRY() GET-ENV() Returns the value of the specified environment variable. Syntax GET-FIELD-VALUE(string-expression) Category Environment Runtime 6. Note: Without the above preparation.  The required record is current. or spaces if the environment variable is not set. the only fields guaranteed to return values are the key fields of the current objects referenced by the program. set or printed it).  The required field on that record is referenced prior to calling get-field-value (see Example below). so it must either be contained in a data field or specified as a quoted alphaliteral. This is optional as the GET-FIELD-VALUE function can be used to obtain a character representation of any type of field. the first element’s value is returned.1 and above See Also SET-ENVIRONMENT() Example: FIELD ws-tmp-directory PIC X(80) SET ws-tmp-directory = GET-ENV("TMPDIR") GET-FIELD-VALUE() Returns the current value of the field whose name is specified in the string expression. This function always returns the character representation of the field.  Array fields should be properly referenced by a subscript. This includes ensuring the following:  Objects required are known at compile time. If an invalid subscript is passed. regardless of its type.See Also START-DIR-SEARCH(). spaces will be returned. This function always returns the numeric value of the field.15 DEFAULT job-code UPPERCASE TITLE "Project:" VALIDATIONS GET job-cost-master // Object is known (1) ON INDEX job-code KEY IS job-code ON ERROR MESSAGE "No such project:" job-code RE-ENTER job-code ELSE // Record is now current (2) END-ON END-VALIDATION ACCEPT lf-name @8.lf-value PIC X(256) BEFORE SET lf-name = "jcm-total-budget-amount" DETAIL ACCEPT job-code @5. jcm-totalbudget-amount.5 PROMPT PAUSE RE-ENTER lf-name END-VALIDATION END-SCREEN //main GET-FIELD-VALUE-NUMERIC() Returns the current value of the field whose name is specified in the string expression. jcm-project-type" VALIDATIONS IF 1 = 0 INSERT job-cost-master ENDIF //Set references to all //fields on the record (3) SET lf-value = GET-FIELD-VALUE(lf-name) //Array fields should be //specified with subscript (4) DISPLAY lf-value @15. Syntax GET-FIELD-VALUE-NUMERIC(string-expression) Category Environment Runtime 6. provided the field type is numeric or a date / time field type.15 DEFAULT lf-name TITLE "JCM Field:" HELP "Enter job-cost-master field eg.15 DEFAULT job-code UPPERCASE TITLE "Project:" VALIDATIONS 143 . jcm-start-date. job-site-details[2]. Otherwise it returns 0.4 and above See Also GET-FIELD-VALUE() Example: #define ALL_NUMERIC_FIELD_TYPES 'N' 'Z' 'F' 'P' 'D' 'T' 'B' 'J' 'L' SCREEN main ALLOWED ENTRY LOCAL lf-name PIC X(40) lf-value PIC X(256) BEFORE SET lf-name = "jcm-total-budget-amount" DETAIL ACCEPT job-code @5. //however get-field-value function needs fieldname with the subscript.STR-LEN(lp-fld) . job-site-details[2]. jcm-project-type" VALIDATIONS IF 1 = 0 INSERT job-cost-master ENDIF //Reference all fields on //record (3) DO get-field-value-for-any-current-record //Determines which get//field-value function to //call PARAMETER lf-name RETURN lf-value DISPLAY lf-value @15.5 PROMPT PAUSE RE-ENTER lf-name END-VALIDATION END-SCREEN //main PROCEDURE get-field-value-for-any-current-record PARAMETER lp-fld LIKE fld-name RETURN lr-fld-value PIC X(256) LOCAL lf-key LIKE fld-name lf-pos PIC 999 lf-sub PIC 999 // SET lr-fld-value = "*Error* Field Unknown" SET lf-pos = PATTERN(lp-fld.15 DEFAULT lf-name TITLE "JCM Field:" HELP "Enter job-cost-master field eg.1)) ELSE // Not expecting an array .passed "fieldname" only SET lf-key = lp-fld SET lf-sub = 1 ENDIF GET dict-field ON INDEX fld-name KEY IS lf-key ON ERROR SET lr-fld-value = "*Error* Field not found in Dictionary" ELSE IF (fld-occurs > 1 // No subscript specified AND NOT ( PATTERN(lp-fld."\]"))) OR (lf-sub NOT BETWEEN 1 AND fld-occurs) // or Invalid subscript // passed SET lr-fld-value = CONCAT("*Error* Array field needs subscript[nn] between 1 and " STR-CONCAT(lf-key). "fieldname[3]" //Dictionary lookup needs fieldname without subscript.lf-pos + 1.GET job-cost-master // Object is known (1) ON INDEX job-code KEY IS job-code ON ERROR MESSAGE "No such project:" job-code RE-ENTER job-code ELSE // Record is now current (2) END-ON END-VALIDATION ACCEPT lf-name @8. SET lf-key = SUB-STRING(lp-fld. jcm-start-date.lf-pos . jcm-totalbudget-amount."\[") IF lf-pos //Passed an array field subscripted as eg.1.1) SET lf-sub = NUM(SUB-STRING(lp-fld. "[" STR(fld-occurs) "]") ELSE 144 ."\[") AND PATTERN(lp-fld. // Arrays referenced by subscript (4) IF lf-sub > 0 AND lf-sub <= fld-occurs SET lf-key = lp-fld // subscript must be included in the call. ENDIF // Field Type . A return value of spaces indicates that no further enumerated values exist. This function is useful when the number of subkeys is unknown.7 and above Notes The (index) value should be zero for the first call and incremented by one for each subsequent call." IN COL 4 BOLD lf-key BOLD 145 . index) Category Environment Runtime 6. GET-FIELDVALUE(lf-key)) ENDIF ENDIF END-ON END-PROCEDURE //get-field-value-for-any-current-record GET-PARAM() Returns the specified program parameter.Decide which function to use (5) // NB: numeric return value is here converted to string anyway. When an application is using these enumeration functions it should not perform any operations that may change the registry key. Syntax GET-REGISTRY-ENUM-KEY(registry-key.1 and above Example: IF GET-PARAM(1) = '-recalc' DO recalculate-values ENDIF GET-REGISTRY-ENUM-KEY() Returns the subkey(s) of the specified Windows registry key or spaces if the registry key is not found. Example: #define MAX_KEYS_TO_CHECK 99 PROCEDURE main LOCAL lf-key PIC X(256) SET lf-key = "HKEY_LOCAL_MACHINE/Software/Pronto" ACCEPT lf-key @5. Syntax GET-PARAM(number) Category Environment Runtime 3. IF fld-type IN { ALL_NUMERIC_FIELD_TYPES } SET lr-fld-value = CONCAT("NUMBER returned: ". or spaces if there is no parameter of that number. This function returns the name of the enumerated registry entry if successful. STR(GETFIELD-VALUE-NUMERIC(lf-key))) ELSE SET lr-fld-value = CONCAT("STRING returned: ".25 PIC X(40) DEFAULT lf-key TITLE "Report on Registry Key:" REPORT 'PRONTO Recursive Registry Report' WIDTH 200 SKIP 2 PRINT "KEY .7v0. Registry keys will not retrieve in the same order displayed in the Registry Editor. " (Default)".STR-CONCAT(lf-subkey)) IN COL lf-col + 2 BOLD DO print-subkey-values PARAMETER STR-CONCAT(lp-key. lf-i) IF lf-subkey <> SPACES PRINT CONCAT("SUBKEY #" STR-CONCAT(LEFT-JUSTIFY(FSTR(lfi." .2.we're done ENDIF END-FOR END-PROCEDURE //print-subkey-values // end of file Sample Report: 146 ."." STR-CONCAT(lf-setting) "=" STR-CONCAT(lf-value).lf-subkey) lp-level + 1 // Recurse to next level down ELSE BREAK // No more subkeys for this folder .lfsuffix) ELSE BREAK // No more values for this subkey .we're done ENDIF END-FOR END-PROCEDURE //print-subkeys PROCEDURE print-subkey-values PARAMETER lp-subkey PIC X(256) lp-level PIC 999 LOCAL lf-setting PIC X(256) lf-value PIC X(256) lf-suffix PIC X(20) lf-col PIC 999 lf-j PIC 999 // SET lf-col = lp-level * 4 FOR lf-j = 0 TO MAX_KEYS_TO_CHECK SET lf-setting = GET-REGISTRY-ENUM-VALUE(STR-CONCAT(lp-subkey)."/".0))).SPACES) PRINT "VALUE #" IN COL lf-col + 4 CONCAT(STR-CONCAT(LEFT-JUSTIFY(ZSTR(lf-j. lf-j.lf-value) IF lf-setting <> SPACES SET lf-suffix = IF-THEN-ELSE(lf-setting = "@".lf-subkey) lp-level DO print-subkeys PARAMETER STR-CONCAT(lp-key.2." ."/".0))).DO print-subkeys PARAMETERS lf-key 1 SKIP 5 REPORT FINISHED END-PROCEDURE //main PROCEDURE print-subkeys PARAMETER lp-key PIC X(256) lp-level PIC 99 LOCAL lf-subkey PIC X(256) lf-col PIC 999 lf-I PIC 999 // SET lf-col = lp-level * 4 FOR lf-i = 0 TO MAX_KEYS_TO_CHECK SET lf-subkey = GET-REGISTRY-ENUM-KEY(lp-key. 147 . GET-REGISTRY-VALUE() Returns the content of the Windows registry for the specified registry key or spaces if the registry key is not found.7v0. If the size of the field is not large enough to store the value. Syntax GET-REGISTRY-ENUM-VALUE (registry-key.7 and above Notes The (index) value should be zero for the first call and incremented by one for each subsequent call. When an application is using these enumeration functions it should not perform any operations that may change the registry key. index. This function returns the name of the enumerated registry entry if successful. A return value of spaces indicates that no further enumerated values exist. Registry keys will not retrieve in the same order displayed in the Registry Editor. The (data-field) parameter is the name of an alphanumeric field that will be set to the value of the registry entry. It will return a name of “@” if the default value of the enumerated key is being returned.GET-REGISTRY-ENUM-VALUE() Returns the value(s) of the specified Windows registry key or spaces if the registry key is not found. Refer to the ‘GET-REGISTRY-ENUM-KEY()‘ section for an example of this function. data-field) Category Environment Runtime 6. then the value will be truncated to fit. Only alphanumeric registry entries are currently supported. This function is useful when the values are unknown. 148 . IF SET-REGISTRY-VALUE(MY_SAVED_PATH. that is. universal time.0 and above Notes The registry key is constructed in a similar manner to a file path.1 and above Notes This is highly suitable in implementing meaningful time and date stamping of transactions. Syntax GID() Category Environment Runtime 3.1 and above Notes Group Code. See Also SET-REGISTRY-VALUE.Syntax GET-REGISTRY-VALUE(registry-key) Category Environment Runtime 5.0) IF DELETE-REGISTRY-VALUE(MY_SAVED_PATH) MESSAGE "Registry entry deleted because path does not exist: " lf-path ENDIF ENDIF END-PROCEDURE //main GID() Returns the group ID number of the current user. Group ID and User ID’s are set up when first registering a user for PRONTO-Xi. Time and date stamping requires meaningful comparisons between values stored on ALL transactions from ALL Time Zones. DELETE-REGISTRY-VALUE Example: #define MY_SAVED_PATH "HKEY_CURRENT_USER/Software/Pronto/MySettings/Path" PROCEDURE main LOCAL lf-path PIC X(100) // Save path noting that it is set to a non-existent directory. except the date-time value returned is in Greenwich Mean Time format. "c:\non_existent_directory") ENDIF //Read it back and verify what we already know SET lf-path = GET-REGISTRY-VALUE(MY_SAVED_PATH) IF NOT FILE-EXISTS(lf-path. Syntax GMT() GMTIME() Category Environment Runtime 4.xls”. See PROADMIN (Enter User Details) Example: MESSAGE "Your Group Code is " USER-GROUP() MESSAGE "Your Group ID is " GID() MESSAGE "Your User ID is " UID() GMT() This function is equivalent to the SYSTIME() function. The time for the local time zone has not been added. Each subkey is separated by a forward slash (/). For example: “HKEY_CLASSES_ROOT/. where a single function captures the precise moment in time and permits comparisons between data captured at two locations in different time zones. user-id) Category Environment Runtime 5.false-value) Notes/Examples This function can be used anywhere that a function/expression can be normally used. otherwise the value of the ELSE expression(s) is returned. the date // and time returned will be gmt. The IF condition can contain any valid conditional/logical expression.See Also SYSTIME() Example: // Assume UNIX 'date' returns. GRANT-DB-SCHEMA() This function attempts to grant access to the specified user to the schema specified by the path. The results of the THEN and ELSE expressions must be compatible (that is both numeric or both alphanumeric). // If the flag on the Date-From-Date-Time and Time-From-Date-Time // functions was true (or '1'). system-administration type program. Syntax GRANT-DB-SCHEMA(path. otherwise it returns the failure error number. the time zone value will be added thus // returning a date and time that will be in your local date and time. It may be useful for a high security level.0) TIME-FROM-DATE-TIME(ws-date-time.user-id) IF ws-status IN VALID_STATII DO process-company-login ENDIF IF-THEN-ELSE() Performs an in-line IF THEN ELSE test within an expression.0 and above Notes This function is not intended for general use. Only relevant on RDBMS systems. The result of the IF-THEN-ELSE function will be the same type as the results of the THEN/ELSE expressions. See Also REVOKE-DB-SCHEMA() Example: SET ws-status = GRANT-DB-SCHEMA(company-path. 149 .0) // // Result: GM Time: 16-FEB-2000 07:08:03 // // The false (or '0') in the DATE-FROM-DATE-TIME or TIME-FROM-DATE-TIME // functions indicates that no time zone is added to the ws-date-time // field and since the ws-date-time fields holds the GM Time.true-value. It returns ZERO if successful. Syntax IF-THEN-ELSE(condition. The function returns the value of the THEN expression if the IF condition is true (or non-zero). for example: // Wed Feb 16 18:08:03 EETDT 2000 // (where EETDT is Daylight Savings adjusted time) // UNIX 'date -u' (for the same moment in time) // would return Wed Feb 16 07:08:03 GMT 2000 // Comparing these two formats for the same moment in time shows // a difference of 'eleven' hours between GMT and EETDT // (Daylight Savings) // GMT() for the same moment reports the GMT // FIELD ws-date-time TYPE DATE-TIME SET ws-date-time = GMT() MESSAGE "GM Time: " DATE-FROM-DATE-TIME(ws-date-time. "Other"))) IS-A-DIR() Returns a True/False result indicating whether the specified file path represents a directory. The THEN and ELSE parameters are expressions.1 and above Notes This function returns TRUE (non-zero) if a directory exists at the path specified. "Journal". "Invoice". "B") It is different from a normal function in that only the required THEN or ELSE expression (parameter) will be evaluated. Syntax LOCAL-CD() Category Environment Runtime 4. Syntax IS-A-DIR(path-name) Category Environment Runtime 4. so a subscripting error will not occur when i is less than or equal to zero. IF-THEN-ELSE(sol-line-type = "JE". SPACES) In this example. For example: SET x = IF-THEN-ELSE(i > 0. except that it always changes the current working directory on the local (client) machine.For example: SET x = IF-THEN-ELSE(i < 0 or i > 10) AND x != SPACES. LOCAL-CD-WITHOUT-CLOSE-ALL() LOCAL-CD-WITHOUT-CLOSE-ALL() This function is the same as the CD-WITHOUT-CLOSE-ALL() function. otherwise FALSE (0). but also to allow the IF condition to test for valid subscript values etc. a[i]. IF-THEN-ELSE(sol-line-type = "IN". DESC = IF-THEN-ELSE(sol-line-type = "CR". DIR() Example: IF NOT IS-A-DIR(lf-filename) OPEN tmp-file FILE IS lf-filename ENDIF LOCAL-CD() This function is the same as the CD() function. "A".1 and above 150 . the THEN expression (a[i]) will only be evaluated if the IF condition (i > 0) is true. except that it always changes the current working directory on the local (client) machine. "Credit". See Also FILE-EXISTS(). and can therefore contain other IF-THEN-ELSE() functions nested within them. CD-WITHOUT-CLOSE-ALL(). This is partly to optimise the function.1 and above See Also CD(). depending upon the result of the IF condition. Syntax LOCAL-CD-WITHOUT-CLOSE-ALL() Category Environment Runtime 4. One possible use of this function is to prevent attempts to open a directory for reading or writing as if it were a file. For example: SELECT *. and today is 21-FEB-2000 SET tmp-mail-text = CONCAT("Sent to Customer: ". 151 .1 and above Notes Reserved for future use. Syntax LOCAL-NO() LOCAL-YES() Category Environment Runtime 4. Syntax LOCAL-DIR() Category Environment Runtime 4. CD-WITHOUT-CLOSE-ALL(). Syntax LOGIN-ID() Category Environment Runtime 3." On ".accountcode ." By ". Comment: Example: FIELD ws-response PIC X IF ws-response = LOCAL-NO() // INDONESIAN users will enter 'T' (Tidak=NO). login = 'eric'.1 and above Notes This function returns a different value from the DIR() function if the PROSERVER environment is set. however. JULIAN-TO-DATE(TODAY())) MESSAGE tmp-mail-text // // Result: Sent to Customer: LAYLA By eric On 21-FEB-YYYY MAIL-ADD-LINE() Adds a line of text to a mail item. LOCAL-CD() LOCAL-DIR() Returns the full path of the current working directory on the local (client) machine. LOGIN-ID() . // ENGLISH users will enter 'N' // The programmer.1 and above Example: FIELD tmp-mail-text PIC X(70) // Construction of a line of mail text for audit purposes // Assume accountcode = 'LAYLA'. See Also DIR() LOCAL-NO and LOCAL-YES() These functions return the equivalent characters to ‘Y’ (for yes) and ‘N’ (for no) in the local language. Presently these functions always return ‘N’ and ‘Y’ respectively.See Also CD(). does not need to know what // letter is entered for NO in any given language ENDIF LOGIN-ID() Returns the login ID (user name) of the current user. Syntax MAIL-ATTACH( file-name. in-body 1 if the file is to be sent in the body of the message.Syntax MAIL-ADD-LINE(text) Category Environment Runtime 4. descriptive-name-of-file. Syntax MAIL-FROM-NAME(name) 152 . conversion.extension Descriptive name of the attachment file to send in the mail message.no conversion remove 1 if the file(s) are to be removed after they are attached.xml’). Syntax MAIL-CANCEL() Category Environment Runtime 4. This can be the name of a PRONTO-Xi report file (#P or ‘. Note: On Windows.1 and above See Also MAIL-START() MAIL-ATTACH() Attaches the specified file to the mail message being generated (using the PRONTO-Xi mail functions) and returns ‘1’ for success and ‘0’ for failure. in-body. See Also MAIL-START() MAIL-CANCEL() Completes the current mail message and removes data. this is effectively zero at all times. descriptivename-offile. "Your Tax Return. For example.convert to HTML. 0 if a separate attachment.xls". Returns TRUE (non-zero) if successful otherwise FALSE (zero).extension. 0 if they are to be left.1 and above Notes HTML format is not currently supported for attachments with the ‘in-body’ flag set for Windows implementations.1 and above See Also MAIL-START() MAIL-FROM-NAME() Sets the descriptive name of the sender of the message and returns non-zero (TRUE) for success and zero (FALSE) for failure. remove ) Category Environment Runtime 6. 0 . 1 . conversion Report conversion flag (for #P or ‘.xml’ files). This will be seen in the email header. and should use the file extension so that the receiving PC will know how to open it. Parameters: file-name Name of the file to attach. Category Environment Runtime 6. // and should include the file extension so the receiving PC will // know how to open it. Example: IF NOT MAIL-REPLY-TO('info@pronto. IF MAIL-ATTACH("c:\tmp\plans.au'. and returns non-zero (TRUE) for success and zero (FALSE) for failure.FALSE.name) Category Environment Runtime 6. the in-body flag must be zero. // The description of the attachment will be seen in the email header.xls".xls" .1 and above See Also MAIL-ATTACH(). // and for this case.STR-CONCAT(login-id).com." ) SET ws-mail-open = MAIL-ADD-LINE(" ") SET ws-mail-open = MAIL-ADD-LINE("Kind Regards.5 v4."Draft Plans for Renovations.xls must exist. Syntax MAIL-REPLY-TO(email-addr. The attachment file // c:\tmp\plans.FALSE) 153 . MAIL-SEND() Example: PROCEDURE main FIELD ws-mail-open TYPE BOOLEAN // Sending an Email with an attachment SET ws-mail-open = MAIL-START("TEST EMAIL") SET ws-mail-open = MAIL-ADD-LINE(CONCAT("Hi ".".") // Attachment // This assumes PRONTO is running locally on a Windows platform.")) SET ws-mail-open = MAIL-ADD-LINE(" ") SET ws-mail-open = MAIL-ADD-LINE("Please find enclosed the changes to the draft plans we discussed last week. otherwise the message will not be sent. Example: IF NOT MAIL-FROM-NAME('Company Mail System') ENDIF MAIL-REPLY-TO() Set the email address and corresponding descriptive name to be used when replying to the current message. 'Company Mail System') ENDIF MAIL-START() Returns the value TRUE (non-zero) if a new mail message is successfully started otherwise FALSE (zero).0.0 and above Notes This function currently has no effect for Windows implementations. This function call does not affect the ‘From’ email address.5 v4.") SET ws-mail-open = MAIL-ADD-LINE("Note that we allowed an extra week in the schedule because we know you will ") SET ws-mail-open = MAIL-ADD-LINE("change your mind again.0) ENDIF IF NOT MAIL-SEND(LOGIN-ID().0. Syntax MAIL-START(text) Category Environment Runtime 4.0 and above Notes This function currently has no effect for Windows implementations. The Architect. 1.MESSAGE "This email was not sent . TRANSLATE " .'The mail message'. ENDIF // IF MAIL-SEND(lp-email-address.Please ensure the attachment exists" ENDIF SET ws-mail-open = NOT MAIL-CANCEL() END-PROCEDURE Mail Functions Example Following is an example using the PRONTO-Xi ‘mail’ functions: // start the mail message. lp-file-name) PRINT CONCAT(TRANSLATE "Account :". Syntax MAIL-SEND(user-id.1. IF MAIL-START(lf-screen-name) ENDIF // Format the mail message REPORT lf-screen-name FORM 'PRONTO_MAIL' FULL-XML NO-MESSAGE SPOOL-ONLY REPORT SECTION IS 'mail_body' // PRINT STR-CONCAT(lf-screen-name.FALSE) // where the flag TRUE.Outstanding Invoices: ") SKIP PRINT CONCAT(TRANSLATE "Attached file :".0 mean // 0 attached file is to be a separate attachment in the mail // 0 do not convert to HTML // 0 do not remove the file after it is attached. for example. That is. lp-auth-accountcode) // SET lf-spoolfile = SPOOL-FILE-NAME() REPORT SECTION FINISHED REPORT FINISHED IF MAIL-ATTACH(lf-spoolfile. until such time as the cancel flag is set or the MAIL-CANCEL function is 154 .1) // where the flags 1.0.0.1. can not send // mail to another user.0.'The mail message'.1 mean // 1 attached file is to be in the body of the mail // 1 convert to HTML // 1 remove the file after it is attached. ENDIF // IF MAIL-ATTACH(lp-file-name.0) // where the flags 0.TRUE. no need to do a mail-cancel() // FALSE Do not send as registered mail ENDIF MAIL-SEND() Sends a mail message.reg-mail-flag) Category Environment Runtime 4. If the cancel flag is not set then it is possible to send the mail message to other users using this function.1 and above Notes The cancel flag can be used to indicate whether or not to finish the mail message when sent. FALSE mean // TRUE Flag the mail as cancelled.cancel-flag. 1 and above Notes This function is not intended for general use.FALSE) MAX-SCREEN-COLUMNS() Returns the maximum number of columns (width) available on the current terminal. The maximum number of rows and columns are defined in the termcaps file entry for the current terminal type. 155 . 80 characters.FALSE) MAIL-SEND("john".TRUE.1 and above Notes This function is not intended for general use. It was previously used to determine if a character-based terminal had compressed mode capabilities to display more than eg. The maximum number of rows and columns are defined in the termcaps file entry for the current terminal type. PRONTO-Xi reports an error if you attempt to display beyond these screen limits.7 and above Notes This function will return the button code as used in the MESSAGE-BUTTONS clause within the MESSAGE-BOX function. See Also MAIL-START() Example: MAIL-SEND("dave". See Also MAX-SCREEN-COLUMNS() MESSAGE-STATUS() This function can be called after the MESSAGE-BOX statement to identify the button that was pressed when displaying a multi-line message box. See Also MAX-SCREEN-ROWS() Example: IF MAX-SCREEN-COLUMNS() >= 132 // Terminal can go to 132 columns DO multi-column-costing-screen ELSE // Must be 80 char terminal mode DO cutdown-column-costing-screen ENDIF MAX-SCREEN-ROWS() Returns the maximum number of rows (height) available on the current terminal. PRONTO-Xi reports an error if you attempt to display beyond these screen limits. Syntax MESSAGE-STATUS() Category Environment Runtime 6.FALSE) MAIL-SEND("fred". The final parameter indicates if the mail should be sent registered.FALSE.called. Syntax MAX-SCREEN-COLUMNS() Category Environment Runtime 3. Syntax MAX-SCREEN-ROWS() Category Environment Runtime 3.FALSE. 1 and above See Also RMDIR() Example: FIELD ws-err-no PIC 9(4) IF CD(CONCAT(GET-ENV("SRC"). Syntax MKDIR(directory-name) Category Environment Runtime 4.See Also MESSAGE-BOX MKDIR() Attempts to create a directory of the specified name. Syntax MODE-NAME() Category Environment Runtime 3. This function is useful for debugging purposes. and returns zero if successful. otherwise an error number. It is mainly used for debugging purposes.1 and above Notes On network versions of PRONTO-RAD. since you can display the mode-name on the screen to follow the progress of the program. Syntax MODIFICATION-TIME(file-name) Category Environment Runtime 4. or zero if the file does not exist. the file is always expected to reside on the local 156 .'/job')) MESSAGE "Found parent directory" SET ws-err-no = MKDIR('mytest') IF NOT ws-err-no MESSAGE "Success" ELSE MESSAGE "Failed to create directory" ENDIF ELSE MESSAGE "Could not find parent directory" ENDIF // // Result: Creates the directory $SRC/job/mytest MODE-NAME() Returns the name of the current screen mode as an alphanumeric field.1 and above Notes This function is not intended for general use. See Also SCREEN-MODE() Example: // As the first statement in DETAIL section of a screen MESSAGE "Screen mode is " MODE-NAME() // // Result: "Screen mode is next-scr" MODIFICATION-TIME() Returns the modification time of the specified file in GMT format. 0) MOUSE-COLUMN() Returns the PRONTO-Xi screen column for the last mouse click detected. Syntax MOUSE-COLUMN() Category Environment Runtime 5.0 and above Notes This function is not intended for general use.1 and above See Also START-DIR-SEARCH().com. or the name of machine if it does not have a node name.pronto.1 and above Example: MESSAGE "Node name: " NODE-NAME() // // Result: "Node name: ourmachine. Syntax MOUSE-ROW() Category Environment Runtime 5. FINISH-DIR-SEARCH() NODE-NAME() Returns the network node name of the current machine. Syntax NEXT-DIR-ENTRY() Category Environment Runtime 3. See Also WAIT-FOR-INPUT() NEXT-DIR-ENTRY() For details on this function call refer to the ‘START-DIR-SEARCH()’ section.machine and not the server. Syntax NODE-NAME() Category Environment Runtime 4. See Also WAIT-FOR-INPUT() MOUSE-ROW() Returns the PRONTO-Xi screen row for the last mouse click detected.au" 157 . Example: // Find Modification Time and Date FIELD ws-full-path-filename PIC X(100) MESSAGE "Date of last modification: " DATE-FROM-DATE-TIME(MODIFICATION-TIME(ws-full-path-filename).0) MESSAGE "TIME of last modification: " TIME-FROM-DATE-TIME(MODIFICATION-TIME(ws-full-path-filename).0 and above Notes This function is not intended for general use.  CLSCTX_REMOTE_SERVER A remote machine context.microsoft. 0 = disabled (default = 0)  CLSCTX_NO_CUSTOM_MARSHAL Specify if the activation should fail if it uses custom marshalling. automatic download of missing classes is enabled: HKEY_CURRENT_USER\Software\Policies\Microsoft\Windows\App Management Value Name: COMClassStore. If the COMClassStore policy enables automatic installation. for example: “Excel. but is loaded in a separate process space. 1 = enabled. ValueType: DWORD. The LocalServer32 or LocalService code that creates and manages objects of this class is run on a different machine. CLSCTX_NO_CODE_DOWNLOAD can be used to explicitly disallow download for an activation.msdn. This is the DLL that runs in the client process and implements client-side structures of this class when instances of the class are accessed remotely.  CLSCTX_NO_CODE_DOWNLOAD Disallows the downloading of code from the Directory Service or the Internet.com/library/  CLSCTX_INPROC_SERVER The code that creates and manages objects of this class is a DLL that runs in the same process as the caller of the function specifying the class context. 158 . 0 = disabled (default = 0) HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\App Management Value Name: COMClassStore. context-flag A number specifying one or more of the following predefined values: Note: The description of each of these values has been taken from the MSDN Library: www. 1 = enabled.  CLSCTX_LOCAL_SERVER The EXE code that creates and manages objects of this class runs on the same machine.Common OLE() Call Parameters The following parameters are used by the OLE function calls: Parameter Description class-id This can be either:  The string format of the object’s ID number. When either of the following registry keys is enabled.  CLSCTX_INPROC_HANDLER The code that manages objects of this class is an in-process handler.Sheet” The program ID format may vary between different languages or locales and should be avoided for applications that may need to run in multiple locales. This flag cannot be set at the same time as CLSCTX_ENABLE_CODE_DOWNLOAD. ValueType: DWORD. for example: “{000208020-0000-0000-C000-000000000046}” Or  The program ID number. 2 = Never log any failures no matter what client specified.  CLSCTX_ENABLE_AAA Enables activate-as-activator (AAA) activations for this activation only. This flag can not be set at the same time as CLSCTX_ENABLE_AAA. 159 . set this value to ‘0’ (recommended) and write the client code to override failures. When the ActivationFailureLoggingLevel is created.Add” error-status The error number returned by a call to OLE-STATUS().  CLSCTX_FROM_DEFAULT_CONTEXT Begin this activation from the default context of the current apartment. ValueType: DWORD. Log by default. Can be either the name of a property or method. This helps prevent the library application from being used in an escalation-of-privilege security attack. Names may be specified as dot separated multi-part names. It can be used with Windows XP and later versions. Any activation where a server process would be launched under the caller’s identity is known as an activate-as-activator (AAA) activation. but clients can override by specifying CLSCTX_NO_FAILURE_LOG in CoCreateInstanceEx.  CLSCTX_NO_FAILURE_LOG Can be used to override the logging of failures in CoCreateInstanceEx. It can be used with Microsoft Windows XP and later versions. This is the only way to disable AAA activations in a library application because the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration is applied only to the server process and not to the library application. MSDN strongly recommends that the value is not set to ‘2’. CLSCTX_ENABLE_CODE_DOWNLOAD Allows the downloading of code from the Directory Service or the Internet. dispatch-name  CLSCTX_DISABLE_AAA Disables activate-as-activator (AAA) activations for this activation only.Workbooks. it is more difficult to diagnose problems. Should there be a need to control customer applications. 0 = Discretionary logging. or it can be the numeric dispatch interface ID of the property or method as returned by OLE-GETDISPATCH-ID(). This flag can not be set at the same time as CLSCTX_DISABLE_AAA. Any activation where a server process would be launched under the caller’s identity is known as an activate-as-activator (AAA) activation. Disabling AAA activations allows an application that runs under a privileged account (such as LocalSystem) to help prevent its identity from being used to launch untrusted components. the following values can determine the status of event logging: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Ole Value Name: ActivationFailureLoggingLevel. the default is ‘0’. for example: “Application. Enabling this flag allows an application to transfer its identity to an activated component. Library applications that use activation calls should always set this flag during those calls. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. When the registry entry is missing. When event logging is disabled. This flag cannot be set at the same time as CLSCTX_NO_CODE_DOWNLOAD. This flag overrides the setting of the EOAC_DISABLE_AAA flag from the EOLE_AUTHENTICATION_CAPABILITIES enumeration. 1 = Always log all failures no matter what the client specified. return-field The name of a field which will store the return value of the property or method being invoked.msdn. parameter-values Optional parameter values required by the property or methods. prop-meth-name The name of a property or method within the interface. queue-size A number specifying the maximum pending events to queue up.comsrvcls. For further information on OLE-INTERFACE refer to the ‘Data Types’ section. Fields that store this should be defined as OLE-INTERFACE. OLE Code Examples This section contains examples of code that utilise the OLE related function calls provided in the PRONTO-RAD 4GL language:  Call an Object Interface  Embed a Calendar inside a PRONTO-Xi Screen  Embed an Internet Explorer Window inside a PRONTO-Xi Screen  Embed a PDF File inside a PRONTO-Xi Screen  Excel Code and Functions  Insert Calendar Event or Task into MS Outlook  Populate Data and Create Chart  Populate Excel Spreadsheet and Create Chart  Replace Bookmarks and Insert Text into Word Documents  Web Components inside a PRONTO-Xi Screen Further examples can be located on the MSDN website: www. If zero is specified a default value will be used.com Call an Object Interface This code example calls an object interface: /////////////////////////////////////////////////// // // Sample 4GL program for OLE automation // /////////////////////////////////////////////////// #define REFID "{FF045A0F-0546-11D4-B9A7-00104B48BC81}" #define APPNAME "Comsrv.microsoft. Note: A return-field may not be an array or an element of an array.1" #define CLSCTX_INPROC_SERVER 1 #define CLSCTX_LOCAL_SERVER 4 FIELD FIELD FIELD FIELD FIELD inst-id advise-cookie event-cookie dummy-ret ret TYPE OLE-INTERFACE TYPE OLE-INTERFACE TYPE OLE-INTERFACE PIC 999 PIC S9(8) 160 . Note: All interface IDs allocated must be released (deallocated) by the application via a call to OLE-RELEASE() when they are no longer needed.interface-id The ID number returned by various functions used to identify a specific interface. The return-field must be of the required type and size of the property or method. FIELD i PIC 99 PROCEDURE main SET inst-id = OLE-GET-ACTIVE-OBJECT(APPNAME) IF inst-id <= 0 SET inst-id = OLE-CREATE-INSTANCE(APPNAME, CLSCTX_INPROC_SERVER) IF inst-id <= 0 ABORT "Can not create instance - error ", OLE-STATUS() END END SET advise-cookie = OLE-ADVISE-EVENT(inst-id, REFID, 32) IF advise-cookie <= 0 ABORT "advise-event failed - ", OLE-ERROR-DESCRIPTION(OLE-STATUS()) END // Call the COMM server IF NOT OLE-CALL-METHOD(advise-cookie, "test1", dummy-ret) MESSAGE "call-method test1 failed - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) END FOR i = 0 TO 19 IF NOT OLE-CALL-METHOD(advise-cookie, "test2", dummy-ret, i) MESSAGE "call-method test2 failed - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) END END // Check to see what events we got back MESSAGE "Press enter for events" REPEAT SET event-cookie = OLE-GET-EVENT(inst-id, advise-cookie) UNTIL event-cookie <= 0 IF NOT OLE-GET-PROPERTY(event-cookie, "DispID", ret) MESSAGE "Could not get DispID - ", OLE-ERROR-DESCRIPTION(OLE-STATUS()) END MESSAGE "Event display ID is ", ret IF NOT OLE-GET-PROPERTY(event-cookie, "InvokeKind", ret) MESSAGE "Could not get InvokeKind - ", OLE-ERROR-DESCRIPTION(OLE-STATUS()) END MESSAGE "Event InvokeKind is ", ret IF NOT OLE-GET-PROPERTY(event-cookie, "ParamCount", ret) MESSAGE "Could not get ParamCount - ", OLE-ERROR-DESCRIPTION(OLE-STATUS()) END MESSAGE "Event ParamCount is ", ret FOR i = 1 TO ret // Can we determine ParamType? IF NOT OLE-GET-PROPERTY(event-cookie, "ParamItem", ret, i) MESSAGE "Could not get ParamItem - ", OLE-ERROR-DESCRIPTION(OLE-STATUS()) END MESSAGE "Event ParamItem is ", ret END IF OLE-RELEASE(event-cookie) END MESSAGE "Event id was ", event-cookie END-REPEAT PAUSE 161 IF OLE-UNADVISE-EVENT(inst-id, advise-cookie) ENDIF IF OLE-RELEASE(advise-cookie) ENDIF IF OLE-RELEASE(inst-id) ENDIF Embed a Calendar inside a PRONTO-Xi Screen This code example embeds a calendar inside a PRONTO-Xi screen. This code example also contains samples of adjusting the calendar properties (for example, the background colour): ///////////////////////////////////////////////////////// // // // Sample 4GL program for OLE automation - Calendar Control // // ///////////////////////////////////////////////////////// FIELD id TYPE OLE-INTERFACE colour PIC 9(10) PROCEDURE main NO-HIDE // SET id = OLE-CREATE-CONTROL("MSCAL.Calendar.7", 5, 5, 8, 30) IF id = 0 MESSAGE "error ID = 0" EXIT ENDIF PAUSE IF NOT OLE-GET-PROPERTY(id, "BackColor", colour) ABORT "Could not get BackColor - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) ENDIF SET colour = colour / 2 IF NOT OLE-PUT-PROPERTY(id, "BackColor", colour) ABORT "Could not put BackColor" ENDIF PAUSE END-PROCEDURE //main ----------------------------------------------- Embed an Internet Explorer Window inside a PRONTO-Xi Screen This code example embeds an Internet Explorer (IE) window inside a PRONTO-Xi screen using a PRONTO-Xi prompt to enter the required Internet address: ///////////////////////////////////////////////////////// // // // Sample 4GL program for OLE automation - Internet Explorer // // ///////////////////////////////////////////////////////// FIELD id TYPE OLE-INTERFACE ret PIC S9(10) web-site PIC X(256) SCREEN main ALLOWED ENTRY 162 FORM-ENTRY BEFORE SET id = OLE-CREATE-CONTROL("Shell.Explorer", 2, 1, 20, 80) IF id = 0 MESSAGE "Can not create control - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) EXIT ENDIF SET web-site = "http://www.pronto-software.com" DETAIL ACCEPT web-site @1,30 PIC X(40) TITLE "URL:" DEFAULT IS web-site CONFIRM AUTO CONFIRMED IF SCREEN-MODE = ENTRY IF NOT OLE-CALL-METHOD(id, "Navigate2", ret, web-site) MESSAGE "Navigate2 failed - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) ENDIF ENDIF END AFTER IF OLE-RELEASE(id) ENDIF END-SCREEN //main ----------------------------------------------------- Embed a PDF File inside a PRONTO-Xi Screen This code example opens a PDF (‘.pdf’) file in an Internet Explorer (IE) window, which is embedded inside a PRONTO-Xi screen: //////////////////////////////////////////////////////// // // // Sample 4GL program for OLE automation - PDF File // // //////////////////////////////////////////////////////// FIELD id TYPE OLE-INTERFACE FIELD ret PIC S9(10) FIELD web-site PIC X(256) SCREEN main WINDOW TITLE 'Stock Item Specs' ALLOWED SEARCH PRIMARY stock-master BEFORE DISPLAY 'Item : ' @2,2 BOX @4.9,2.8 TO @23,79.5 SUNKEN COLOUR BLACK ON WHITE ABSOLUTE-COORDINATES SET id = OLE-CREATE-CONTROL("Shell.Explorer", 4, 2, 18, 76.5) IF id = 0 MESSAGE "Can not create control - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) EXIT ENDIF SET web-site = 'C:\Documents and Settings\My Documents\sample.pdf' DETAIL ACCEPT stock-code @2,12 DISPLAY stk-description @2,32 // 163 IF NOT OLE-CALL-METHOD(id, "Navigate2", ret, web-site) MESSAGE "Navigate2 failed - " OLE-ERROR-DESCRIPTION(OLE-STATUS()) ENDIF CONFIRM AUTO CONFIRMED END-CONFIRM AFTER IF OLE-RELEASE(id) ENDIF END-SCREEN //main -------------------------------------------------- Excel Code and Functions This code example contains Excel code using code libraries and select functions (from Excel) to manipulate PRONTO-Xi data to/from Excel spreadsheets: ///////////////////////////////////////// // Sample 4GL program for OLE automation - Excel // // For a Full list of methods and properties available // See microsoft excel // [ Open excel > Tools > Macros > VB Editor > Help > VB Help ] // //////////////////////////////////////////// #define APPNAME "Excel.Application" FIELD wb-id ws-path ws-alpha ws-numeric TYPE OLE-INTERFACE PIC X(256) PIC X(30) PIC S9(8)V9999 //link "../../clib/clib100.spl" LINK "clib/clib100.spl" #include "../../../include/i8excel.spl" PROCEDURE main /////////////////////////////////////// // Starts Excel //////////////////////////////////////// DO clib100-start-excel RETURNING i8excel-error i8excel-instance-id /////////////////////////////////////// // Resets all ole controls if there is an error //////////////////////////////////////// I8EXCEL_ERROR_HANDLE(TRUE) ////////////////////////////////////// //Adds a workbook - create a new spreadsheet ///////////////////////////////////////// DO clib100-add-new-workbook PARAMETER i8excel-instance-id SPACES RETURNING i8excel-error i8excel-workbook-id I8EXCEL_ERROR_HANDLE(TRUE) ////////////////////////////////////////// //Opens a workbook ////////////////////////////////////////// //DO clib100-open-workbook // PARAMETER i8excel-instance-id "C:\SAMPLE.XLS" // RETURNING i8excel-error wb-id //IF i8excel-error != SPACE 164 1) SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-range-id. "Font. i8excel-dummy-ret) END ////////////////////////////////////// // To populate ///////////////////////////////////// DO clib100-fill-a-cell PARAMETERS i8excel-worksheet-id "A1" "Sample" DO clib100-fill-a-cell PARAMETERS i8excel-worksheet-id "A2" "45" ///////////////////////////////////// // To Read //////////////////////////////////// DO clib100-get-alpha-cell PARAMETERS i8excel-worksheet-id "A1" RETURNING ws-alpha DO clib100-get-numeric-cell PARAMETERS i8excel-worksheet-id "A2" RETURNING ws-numeric MESSAGE "These values were retrieved from A1 and A2 >" ws-alpha " & " ws-numeric // /////////////////////////////////////// // //////////////////////////////////////// // To format cells // // First select the cells or range of cells.//This should fail unless file exists.Clear". 165 ."Name". Adds it if it does not exist ///////////////////////////////////////// DO clib100-add-new-worksheet PARAMETER i8excel-instance-id 1 RETURNING i8excel-error i8excel-worksheet-id I8EXCEL_ERROR_HANDLE(TRUE) // //////////////////////////////////////// // This will name the sheet ."Sample") ////////////////////////////////////// // Now to work with any data a cell or range of cells needs to be selected. /////////////////////////////////////// SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-instance-id. // IF OLE-GET-PROPERTY(i8excel-worksheet-id. TRUE) ///////////////////////////////////////// //Makes sheet current . "Application. "Range". "Cells. // Once this is done it is possible to read or write to the cell (or cells) // // Some libraries have been made to write to and read from a cell // /////////////////////////////////////// // To clear Cells ////////////////////////////////////// IF NOT OLE-CALL-METHOD(i8excel-worksheet-id. "Font.Visible". "A2") //////////////////////////////////////// // These statements format the cells /////////////////////////////////////// SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-range-id. //ENDIF /////////////////////////////////////// //Makes the workbook Visible. i8excel-range-id. "A1".Size".."Sample" ////////////////////////////////////// SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-worksheet-id.Bold". 20) SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-range-id. "UnProtect".AutoFit". // // This will select all cells used. "UsedRange"."Font. i8excel-range-id) ///////////////////////////////////////////// // Can use this to unprotect protected cells. 24) ////////////////////////////////////// // A border drawing library has been created as well // (Constants are found in i8excel) ///////////////////////////////////// DO clib100-draw-border PARAMETER i8excel-range-id xlEdgeTop xlContinuous 1 xlThick DO clib100-draw-border PARAMETER i8excel-range-id xlEdgeBottom xlContinuous 1 xlThin ///////////////////////////////// // This will autofit the cells ////////////////////////////////// SET i8excel-xl = OLE-CALL-METHOD(i8excel-range-id. xlCenter) SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-range-id.ColorIndex"."Arial") SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-range-id. "Columns. "Interior. i8excel-dummy-ret) ENDIF ////////////////////////////////// // Can do a global replace on a sheet. SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-worksheet-id. "Sample" "Replaced Sample") ENDIF SET i8excel-xl = OLE-CALL-METHOD(i8excel-range-id. "Columns. i8excel-dummy-ret.Name". "PageSetup.PrintTitleRows". IF OLE-GET-PROPERTY(i8excel-worksheet-id.AutoFit"."Replace". i8excel-dummy-ret) SET i8excel-xl = OLE-RELEASE(i8excel-range-id) ENDIF // ///////////////////////////////// // 166 .. "$1:$4") // ///////////////////////////// // Other selection properties that have used. /////////////////////////////////////// IF NOT OLE-CALL-METHOD(i8excel-worksheet-id. i8excel-dummy-ret) ///////////////////////////////// // Must always remember to release the selected cells //////////////////////////////// SET i8excel-xl = OLE-RELEASE(i8excel-range-id) ENDIF /////////////////////////////// // Other formatting // This will set the top 4 rows as titles on each page. "HorizontalAlignment". (A smaller range could be used) ///////////////////////////////// IF NOT OLE-CALL-METHOD(i8excel-range-id. i8excel-dummy-ret) //////////////////////////////// // Some printing functions. false) // ///////////////////////////////// // To minimise the sheet ///////////////////////////////// SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-instance-id. ws-path) SET i8excel-xl = OLE-CALL-METHOD(i8excel-workbook-id.xlMinimized) ///////////////////////////////// // To maximise the sheet ////////////////////////////////// SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-instance-id. "C:\TryThis. ws-path. "Application.xlMaximized) ////////////////////////////////// // To Save //////////////////////////////// SET i8excel-xl = OLE-CALL-METHOD(i8excel-instance-id. "Application. "Save".DisplayAlerts". the alerts can be disabled // with this statement SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-instance-id.Application" 167 .// Sometimes Excel will pop up alerts. "Application.WindowState". i8excel-dummy-ret. "Application.Outlook ///////////////////////////////////////////////////// #define APPNAME "Outlook. i8excel-dummy-ret ) END-CONFIRM //////////////////////////////// // Always release ole controls //////////////////////////////// IF OLE-RELEASE(i8excel-worksheet-id) ENDIF IF OLE-RELEASE(i8excel-workbook-id) ENDIF IF OLE-RELEASE(i8excel-instance-id) ENDIF END-PROCEDURE //main --------------------- Insert Calendar Event or Task into MS Outlook This code example inserts a calendar event or task event into MS Outlook: ///////////////////////////////////////////////////// // Sample 4GL program for OLE automation . // I am sure there is a statement to set the default printer ///////////////////////////////// SET i8excel-xl = OLE-CALL-METHOD(i8excel-worksheet-id.DisplayAlerts".GetSaveAsFilename".xls") SET i8excel-xl = OLE-CALL-METHOD(i8excel-workbook-id.WindowState". i8excel-dummy-ret) // SET i8excel-xl = OLE-PUT-PROPERTY(i8excel-instance-id. "Application. "SaveAs". Close". "PrintOut". true) ////////////////////////////////// // ///////////////////////////////// /// CONFIRM PROMPT "Do you want to close the workbook" CONFIRMED SET i8excel-xl = OLE-CALL-METHOD(i8excel-workbook-id. TODAY()) SET ws-xl = OLE-PUT-PROPERTY(item-id. STR(YEAR(TODAY())).-1) SET ws-xl = OLE-PUT-PROPERTY(item-id."The email text. "/".dummy-ret) ENDIF // // Insert Task Item IF OLE-CALL-METHOD(outlook-id."Subject". CLSCTX_LOCAL_SERVER) IF outlook-id <= 0 ABORT "Cannot create instance .STR(MONTH(TODAY())). "/". ver) ABORT "Could not get version property: ".TODAY()) SET ws-xl = OLE-PUT-PROPERTY(item-id.namespace-id. CONCAT(STR(DAY(TODAY())).error ".FIELD FIELD FIELD FIELD FIELD FIELD // FIELD FIELD FIELD FIELD FIELD FIELD // outlook-id TYPE OLE-INTERFACE task-folder-id TYPE OLE-INTERFACE calendar-id TYPE OLE-INTERFACE namespace-id TYPE OLE-INTERFACE item-id TYPE OLE-INTERFACE item-no TYPE numeric ver dummy-ret ws-a ws-b ws-c ws-d PIC X(60) PIC 999 PIC X(40) TYPE DATE-TIME TYPE DATE-TIME PIC X(40) ws-range-id ws-xl q ws-path i PIC S9(8) TYPE BOOLEAN PIC 9 TYPE STRING PIC X(256) PIC 999 PROCEDURE main SET outlook-id = OLE-GET-ACTIVE-OBJECT(APPNAME) IF outlook-id <= 0 SET outlook-id = OLE-CREATE-INSTANCE(APPNAME."Save". CONCAT(STR(DAY(TODAY()))." 8:30:00 AM")) 168 . OLE-STATUS() END END IF NOT OLE-GET-PROPERTY(outlook-id. "/".0) SET ws-xl = OLE-PUT-PROPERTY(item-id. STR(YEAR(TODAY())).30) SET ws-xl = OLE-PUT-PROPERTY(item-id.item-id.Version". " 8:00:00 PM")) SET ws-xl = OLE-PUT-PROPERTY(item-id."ReminderMinutesBeforeStart"."CreateItem". "/"."Body". "GetNameSpace". STR(MONTH(TODAY())). " 8:30:00 PM")) SET ws-xl = OLE-PUT-PROPERTY(item-id. STR(YEAR(TODAY())).") SET ws-xl = OLE-PUT-PROPERTY(item-id.3) SET ws-xl = OLE-PUT-PROPERTY(item-id."CreateItem"."ReminderSet".item-id. "End". "OLE inserted Calendar Item") SET ws-xl = OLE-CALL-METHOD(item-id."Body"."Sensitivity"."DueDate". OLE-STATUS() END IF NOT OLE-GET-PROPERTY(outlook-id. "/". "/". "Ole inserted Task .1) SET ws-xl = OLE-PUT-PROPERTY(item-id. "Application. "Start"."StartDate"."ReminderTime".Body of the task") SET ws-xl = OLE-PUT-PROPERTY(item-id. CONCAT(STR(DAY(TODAY())). STR(MONTH(TODAY()))."MAPI") ABORT "No namespace" ENDIF // // Insert Calendar Item IF OLE-CALL-METHOD(outlook-id. Font.error ". OLE-STATUS().Italic". 0) MESSAGE "put-property error for Bold" ENDIF IF NOT OLE-PUT-PROPERTY(cookie. 1) MESSAGE "Could not put-property Visible" END PAUSE IF OLE-RELEASE(cookie) ENDIF END-PROCEDURE //main ---------------------------------------------------------PROCEDURE fill-sheet-font LOCAL FIELD axes-id TYPE OLE-INTERFACE // IF NOT OLE-PUT-PROPERTY(cookie. "Application.Datasheet."Subject".dummy-ret) OLE-RELEASE(outlook-id) OLE-RELEASE(item-id) OLE-RELEASE(namespace-id) //main --------------------------------------------- Populate Data and Create Chart This code example is similar to the ‘Populate Excel Spreadsheet and Create Chart’ example.MS Graph // ////////////////////////////////////////////////// #define APPNAME "MSGraph. "Application. but uses Microsoft components rather than Excel components: ////////////////////////////////////////////////// // // Sample 4GL program for OLE automation .Font.Size". 14) MESSAGE "put-property error for Size" ENDIF IF NOT OLE-PUT-PROPERTY(cookie.Datasheet.Name". OLE-ERROR-DESCRIPTION(OLE-STATUS()) EXIT END DO fill-sheet-font DO fill-sheet IF NOT OLE-PUT-PROPERTY(cookie.Chart" #define CLSCTX_LOCAL_SERVER 4 FIELD cookie TYPE OLE-INTERFACE FIELD ver PIC X(60) PROCEDURE main SET cookie = OLE-GET-ACTIVE-OBJECT(APPNAME) IF cookie <= 0 SET cookie = OLE-CREATE-INSTANCE(APPNAME. "Application.SET ws-xl SET ws-xl ENDIF // SET ws-xl = SET ws-xl = SET ws-xl = END-PROCEDURE = OLE-PUT-PROPERTY(item-id.". CLSCTX_LOCAL_SERVER) IF cookie <= 0 MESSAGE "Cannot create instance .Font.Font. OLE-STATUS() EXIT END END IF NOT OLE-GET-PROPERTY(cookie. "Application. 1) MESSAGE "put-property error for Italic" ENDIF IF NOT OLE-PUT-PROPERTY(cookie.Version".Datasheet. ver) MESSAGE "Could not get version property: ". " .Bold". "Application.Visible".Datasheet."Save". "Application."OLE inserted Task Item") = OLE-CALL-METHOD(item-id. "Tahoma") 169 . "Application.Caption".ChartTitle.HasTitle".error ". axes-id.2) MESSAGE "Could not get axes id . "PRONTO-Xi Chart") MESSAGE "put-property error for chart title" ENDIF // // IF NOT OLE-PUT-PROPERTY(cookie.Chart. "Stock Items") MESSAGE "put-property title caption failed" END IF NOT OLE-RELEASE(axes-id) ENDIF ENDIF // // // IF NOT OLE-GET-PROPERTY(cookie. TRUE) MESSAGE "put-property HasTitle failed" ENDIF IF NOT OLE-PUT-PROPERTY(axes-id. "The Values in Zillions") MESSAGE "put-property title caption failed" END IF NOT OLE-RELEASE(axes-id) ENDIF ENDIF // /// END-PROCEDURE //fill-sheet-font PROCEDURE fill-sheet LOCAL FIELD dummy-ret PIC 9 // IF NOT OLE-CALL-METHOD(cookie.Datasheet. "Axes". OLE-STATUS() OLE-ERROR-DESCRIPTION(OLE-STATUS()) ELSE IF NOT OLE-PUT-PROPERTY(axes-id. "Application. "PRONTO-Xi Chart") MESSAGE "put-property error for chart title" ENDIF // IF NOT OLE-PUT-PROPERTY(cookie.HasTitle". "HasTitle". "Application.Caption".ChartTitle. axes-id. TRUE) MESSAGE "put-property HasTitle failed" ENDIF IF NOT OLE-PUT-PROPERTY(axes-id. "Application.Text". "Application. OLE-STATUS() OLE-ERROR-DESCRIPTION(OLE-STATUS()) ELSE IF NOT OLE-PUT-PROPERTY(axes-id.MESSAGE "put-property error for name" ENDIF // IF NOT OLE-PUT-PROPERTY(cookie.Caption".Chart. "PRONTO-Xi Chart") MESSAGE "put-property error for window caption" OLE-STATUS() OLE-ERROR-DESCRIPTION(OLE-STATUS()) ENDIF // IF NOT OLE-GET-PROPERTY(cookie.1) MESSAGE "Could not get axes id . TRUE) MESSAGE "put-property error for has chart title text" ENDIF IF NOT OLE-PUT-PROPERTY(cookie.Chart.error ". "Application.Chart. "AxisTitle. TRUE) MESSAGE "put-property error for has chart title text" ENDIF IF NOT OLE-PUT-PROPERTY(cookie.Clear".Text". "HasTitle". "Axes". "AxisTitle. dummy-ret) 170 .Cells. Datasheet. "Column 1" DO fill-a-cell PARAMETERS ARE "B0".error ".Range". "Row 1" DO fill-a-cell PARAMETERS ARE "02". "22. "24" DO fill-a-cell PARAMETERS ARE "B4".1" DO fill-a-cell PARAMETERS ARE "B1". p-row-col. range-id. "Row 3" DO fill-a-cell PARAMETERS ARE "04". "21.3" DO fill-a-cell PARAMETERS ARE "D2". "20. "Column 4" DO fill-a-cell PARAMETERS ARE "01".6" DO fill-a-cell PARAMETERS ARE "C3".Excel scatter graph /////////////////////////////////////////////////////// #define APPNAME "Excel. "Value".4" DO fill-a-cell PARAMETERS ARE "A2".1" DO fill-a-cell PARAMETERS ARE "C1".6" DO fill-a-cell PARAMETERS ARE "A3". "30.1" DO fill-a-cell PARAMETERS ARE "B2". "21. "25" DO fill-a-cell PARAMETERS ARE "D4". "21.8" DO fill-a-cell PARAMETERS ARE "B3". "18.MESSAGE "call-method clear failed" END // DO fill-a-cell PARAMETERS ARE "A0". "25.1" DO fill-a-cell PARAMETERS ARE "D1". "31. OLE-STATUS() EXIT END IF NOT OLE-PUT-PROPERTY(range-id.6" DO fill-a-cell PARAMETERS ARE "D3". "Column 2" DO fill-a-cell PARAMETERS ARE "C0". "30" DO fill-a-cell PARAMETERS ARE "C4". "30.Application" #define CLSCTX_LOCAL_SERVER 4 FIELD FIELD FIELD FIELD FIELD inst-id wb-id ws-id chart-id ver TYPE OLE-INTERFACE TYPE OLE-INTERFACE TYPE OLE-INTERFACE TYPE OLE-INTERFACE PIC X(60) 171 . "Row 4" DO fill-a-cell PARAMETERS ARE "A1". "Column 3" DO fill-a-cell PARAMETERS ARE "D0". "Row 2" DO fill-a-cell PARAMETERS ARE "03". "19. "Application. "33" DO fill-a-cell PARAMETERS ARE "A4".3" DO fill-a-cell PARAMETERS ARE "C2".1" END-PROCEDURE //fill-sheet ---------------------------------------------------PROCEDURE fill-a-cell PARAMETERS p-row-col PIC X(20) p-text PIC X(80) LOCAL FIELD range-id TYPE OLE-INTERFACE IF NOT OLE-GET-PROPERTY(cookie. "32. p-row-col) MESSAGE "Could not get range id . p-text) MESSAGE "put-property value failed" END IF NOT OLE-RELEASE(range-id) ENDIF END-PROCEDURE //fill-a-cell --------------------------------------------------- Populate Excel Spreadsheet and Create Chart This code example populates an Excel spreadsheet with predefined data and creates a chart from the data within the same spreadsheet: ////////////////////////////////////////////////////// // Sample 4GL program for OLE automation . Visible". 2) MESSAGE "call-method SetSourceData failed" OLE-ERROR-DESCRIPTION(OLE-STATUS()) END IF NOT OLE-PUT-PROPERTY(chart-id.Add". 1) ABORT "Could not get workbook id . ver) ABORT "Could not get version property: ".add failed" END // Get first workbook IF NOT OLE-GET-PROPERTY(inst-id. range-id.Workbooks. OLE-STATUS() END END IF NOT OLE-GET-PROPERTY(inst-id.Add". "WorkSheets.Item". "Application.Item". true) ABORT "Could not put-property Visible" END IF OLE-RELEASE(chart-id) ENDIF IF OLE-RELEASE(ws-id) ENDIF IF OLE-RELEASE(wb-id) ENDIF IF OLE-RELEASE(inst-id) ENDIF END-PROCEDURE //main ---------------------------------PROCEDURE chart-sheet LOCAL FIELD range-id TYPE OLE-INTERFACE IF NOT OLE-PUT-PROPERTY(chart-id. "Application. 1) ABORT "Could not get charts item id . OLE-STATUS() END IF NOT OLE-GET-PROPERTY(wb-id. "Charts.Version". 74) ABORT "put-property error for ChartType" ENDIF IF NOT OLE-GET-PROPERTY(ws-id. wb-id.error ". " . chart-id. OLE-STATUS() END // Get first worksheet in workbook IF NOT OLE-GET-PROPERTY(wb-id. "Application.Charts.error ". true) MESSAGE "put-property error for HasTitle" OLE-ERROR-DESCRIPTION(OLE-STATUS()) 172 . dummy-ret. "Application.error ". "Range". 1) ABORT "Could not get worksheets item id . OLE-STATUS() END DO fill-sheet DO chart-sheet IF NOT OLE-PUT-PROPERTY(inst-id. "A1". CLSCTX_LOCAL_SERVER) IF inst-id <= 0 ABORT "Cannot create instance . "SetSourceData". "B10") ABORT "Could not get range id . "ChartType".Workbooks.".error ".Item". ws-id. OLE-ERROR-DESCRIPTION(OLE-STATUS()) END IF NOT OLE-CALL-METHOD(inst-id.add failed" END IF NOT OLE-CALL-METHOD(inst-id.error ". range-id. dummy-ret) ABORT "call-method charts. OLE-STATUS() END MESSAGE "range is " range-id IF NOT OLE-CALL-METHOD(chart-id. "HasTitle". dummy-ret) ABORT "call-method workbooks. "Application.FIELD dummy-ret PIC 999 PROCEDURE main SET inst-id = OLE-GET-ACTIVE-OBJECT(APPNAME) IF inst-id <= 0 SET inst-id = OLE-CREATE-INSTANCE(APPNAME. OLE-STATUS(). "=rand()" "A10". "HasLegend".Font. "Axes". "TickLabels.Text". "=rand()" "B5".error ". "=rand()" "B4". "HasMajorGridLines". "=rand()" "A4". "Sample XY Scatter Chart") MESSAGE "put-property error for Title" ENDIF IF NOT OLE-PUT-PROPERTY(chart-id.NumberFormat". "TickLabels. true) ABORT "put-property error for maximumscale" ENDIF IF NOT OLE-PUT-PROPERTY(axis-id. "MaximumScale". "=rand()" "A9". "=rand()" "A5". "Y" "A2". 2 DO set-chart-axes PARAMETERS chart-id.Size". "=rand()" "B9".Interior. "Cells. axis-id.ENDIF IF NOT OLE-PUT-PROPERTY(chart-id. "=rand()" "A6". 9) ABORT "put-property error for font" ENDIF IF NOT OLE-PUT-PROPERTY(axis-id. TRUE) ABORT "put-property error for hasmajorgridlines" ENDIF PROCEDURE fill-sheet LOCAL FIELD dummy-ret PIC 9 IF NOT OLE-CALL-METHOD(ws-id.ColorIndex". axis-type) ABORT "Could not get axis id . dummy-ret) ABORT "call-method clear failed" END DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO DO fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell fill-a-cell PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS PARAMETERS ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE ARE "A1". "=rand()" "B2". "=rand()" "B8". "0. "=rand()" "B6". "=rand()" 173 . "=rand()" "A8". OLE-STATUS() END IF NOT OLE-PUT-PROPERTY(axis-id. 1 IF NOT OLE-PUT-PROPERTY(chart-id. "X" "B1". "=rand()" "A3". "=rand()" "B10".Clear".00") ABORT "put-property error for numberformat" ENDIF IF NOT OLE-PUT-PROPERTY(axis-id. "ChartTitle. "PlotArea. "=rand()" "B3". 19) MESSAGE "put-property error for ColorIndex" ENDIF IF OLE-RELEASE(range-id) ENDIF PROCEDURE set-chart-axes PARAMETERS chart-id PIC S9(8) axis-type PIC 99 LOCAL FIELD axis-id PIC S9(8) IF NOT OLE-GET-PROPERTY(chart-id. "=rand()" "B7". true) MESSAGE "put-property error for HasLegend" ENDIF DO set-chart-axes PARAMETERS chart-id. "=rand()" "A7". range-id. ver) ABORT "Could not get version property: ".error ". This code example also contains samples of other Word methods and properties.. p-row-col. go to a Word // Document and follow this menu path. "Application.PROCEDURE fill-a-cell PARAMETERS p-row-col PIC X(20) p-text PIC X(80) LOCAL FIELD range-id PIC S9(8) IF NOT OLE-GET-PROPERTY(ws-id. p-text) ABORT "put-property value failed" END IF NOT OLE-RELEASE(range-id) ENDIF Replace Bookmarks and Insert Text into Word Documents This code example opens a new Word document (‘. CLSCTX_LOCAL_SERVER) IF inst-id <= 0 ABORT "Cannot create instance . OLE-STATUS() END ///////////////////////////////////// 174 . // // To find the many Word ole properties and functions./include/i8word.Word. OLE-STATUS() END IF NOT OLE-PUT-PROPERTY(range-id. // // Tools > Macros > VB editor > Help > MS VB help > MS Word VB Reference // // ///////////////////////////////////////////////// #define APPNAME "Word./.spl" FIELD FIELD FIELD FIELD FIELD FIELD inst-id wb-id ws-id ver dummy-ret dummy-ret-a ws-range-id ws-xl i tmp-bookmark tmp-index TYPE OLE-INTERFACE TYPE OLE-INTERFACE TYPE OLE-INTERFACE PIC X(60) PIC 999 PIC X(100) PIC S9(8) PIC S9(8) PIC 999 TYPE string TYPE numeric PROCEDURE main ////////////////////////////////////// // Opens up a word session ////////////////////////////////////// SET inst-id = OLE-GET-ACTIVE-OBJECT(APPNAME) IF inst-id <= 0 SET inst-id = OLE-CREATE-INSTANCE(APPNAME. ///////////////////////////////////////////////// // Sample 4GL program for OLE automation ./.dot’) and provides samples of how to replace bookmarks and insert text. "Range".error ".. "Value".Version". OLE-STATUS() END END IF NOT OLE-GET-PROPERTY(inst-id. p-row-col) ABORT "Could not get range id ..doc’) or Word template (‘.Application" #include ". "Application.OK //////////////////////////////////////// SET ws-xl = OLE-PUT-PROPERTY(inst-id.dummy-ret) // ENDIF ////////////////////////////////////// // Help in here will show you all the commands required to manipulate Word //(select help from the visual basic editor) /////////////////////////////////////// IF OLE-PUT-PROPERTY(inst-id. ///////////////////////////////////////// IF OLE-GET-PROPERTY(inst-id. "Inserted text at cursor position") ////////////////////////////////////// // Sets the printer(uses default if not set) /////////////////////////////////////// IF OLE-PUT-PROPERTY(inst-id."Selection."Selection.MoveDown".Visible".Add". true) ///////////////////////////////////////// // This Block is a way of replacing bookmarks if they exist.i) FOR tmp-index = i DOWN TO 1 IF OLE-CALL-METHOD(wb-id."ShowVisualBasicEditor". dummy-ret. dummy-ret .TypeText".doc") MESSAGE "Template document not added" //////////////////////////////// // Just opens up a document(blank) //////////////////////////////// IF NOT OLE-CALL-METHOD(inst-id."Selection.wdLine.dummy-ret) SET ws-xl = OLE-CALL-METHOD(inst-id.Bookmarks". "Name"."Application."lp0") ENDIF ////////////////////////////////////// // Prints spreadsheet ////////////////////////////////////// // IF OLE-CALL-METHOD(inst-id. "Item".// Creates a new Document from the template Doc .OK ////////////////////////////////////// IF NOT OLE-CALL-METHOD(inst-id.tmp-index) IF OLE-GET-PROPERTY(ws-range-id. dummy-ret) MESSAGE "no add" END END //////////////////////////////////////// // Displays The Document .ws-range-id."Select".wb-id) IF OLE-GET-PROPERTY(wb-id. IF OLE-CALL-METHOD(ws-range-id.10) //////////////////////////////////////// // Insert Text /////////////////////////////////////// SET ws-xl = OLE-CALL-METHOD(inst-id.PrintOut"."Bookmark replacing text") ENDIF ENDIF ENDIF END-FOR ENDIF ENDIF // //////////////////////////////////////// // Moves cursor down 10 lines //////////////////////////////////////// SET ws-xl = OLE-CALL-METHOD(inst-id.dummy-ret.dummy-ret. "Application.Documents. "ActivePrinter". "Application.Documents.tmp-bookmark) // You could compare tmp-bookmark to the actual bookmark // before subbing text.true) ENDIF /////////////////////////////////// //Quits Spreadsheet(no Save) 175 . "ActiveDocument.Add"."Count"."C:\sms.TypeText". Excel scatter graph // // /////////////////////////////////////// FIELD sheet-id graph-id chart-id ver dummy-ret TYPE OLE-INTERFACE TYPE OLE-INTERFACE TYPE OLE-INTERFACE PIC X(60) PIC 999 PROCEDURE main DO main-control IF OLE-RELEASE(sheet-id) END IF OLE-RELEASE(graph-id) END END-PROCEDURE //main ---------------------PROCEDURE main-control WINDOW NO-HIDE SET sheet-id = OLE-CREATE-CONTROL("OWC10. 1. dummy-ret) ABORT "call-method cells clear failed . 176 . 14.Spreadsheet.Clear".wdDoNotSaveChanges) ENDIF /////////////////////////////////// // Releases all ole interfaces /////////////////////////////////// IF OLE-RELEASE(ws-id) ENDIF IF OLE-RELEASE(wb-id) ENDIF IF OLE-RELEASE(inst-id) ENDIF END-PROCEDURE //main --------------------- Web Components inside a PRONTO-Xi Screen This code example uses web components inside a PRONTO-Xi screen.". for example.error ". using Windows components to simulate Excel to allow entry of data for a graph and display the details in graph format: //////////////////////////////////////// // // // Sample 4GL program for OLE automation . 10.10". OLE-ERROR-DESCRIPTION(OLE-STATUS()) END SET graph-id = OLE-CREATE-CONTROL("OWC10. 1.Cells. "ActiveSheet.error ".Chartspace. 80) IF graph-id <= 0 ABORT "Cannot create chartspace control ./////////////////////////////////// MESSAGE "After this the word doco will close" IF OLE-CALL-METHOD(inst-id. "Application. 8.Quit".10". 2. dummy-ret. 80) IF sheet-id <= 0 ABORT "Cannot create spreadsheet control . OLE-ERROR-DESCRIPTION(OLE-STATUS()) END DO fill-sheet DO fill-graph PAUSE END-PROCEDURE //main-control -----------------PROCEDURE fill-sheet IF NOT OLE-CALL-METHOD(sheet-id. "Current" DO fill-sheet-cell PARAMETERS 6. "Transit" DO fill-sheet-cell PARAMETERS 9. "6" DO fill-sheet-cell PARAMETERS 4. "Consignment" DO fill-sheet-cell PARAMETERS 3. "0" DO fill-sheet-cell PARAMETERS 8. "Value". "Charts. "0" DO fill-sheet-cell PARAMETERS 5. "ActiveSheet. 2. 1. 1. 1. x) ABORT "Could not get cells id . OLE-STATUS() END IF NOT OLE-PUT-PROPERTY(cells-id. "4" END-PROCEDURE //fill-sheet --------------------PROCEDURE fill-sheet-cell PARAMETERS ARE y PIC 99 x PIC 99 txt PIC X(40) LOCAL FIELD cells-id TYPE OLE-INTERFACE IF NOT OLE-GET-PROPERTY(sheet-id. 2. 1. dummy-ret) ABORT "call-method charts. "On Hand" DO fill-sheet-cell PARAMETERS 4. 2." 177 . 1. 2. "Clear". y. 1. 1. "Balances" DO fill-sheet-cell PARAMETERS 2." OLE-ERROR-DESCRIPTION(OLE-STATUS()) END IF NOT OLE-CALL-METHOD(graph-id. 2.Add". 2. "0" DO fill-sheet-cell PARAMETERS 3. "2" DO fill-sheet-cell PARAMETERS 6. "0" DO fill-sheet-cell PARAMETERS 9. "Available" DO fill-sheet-cell PARAMETERS 1. txt) ABORT "put property value failed " OLE-ERROR-DESCRIPTION(OLE-STATUS()) END IF OLE-RELEASE(cells-id) ENDIF END-PROCEDURE //fill-sheet-cell -----------------PROCEDURE fill-graph IF NOT OLE-CALL-METHOD(graph-id. "0" DO fill-sheet-cell PARAMETERS 7. 2.error ".OLE-ERROR-DESCRIPTION(OLE-STATUS()) END DO fill-sheet-cell PARAMETERS 2.Cells". dummy-ret) ABORT "call-method sheet clear failed . "Forward" DO fill-sheet-cell PARAMETERS 8.add failed . cells-id. "Internal" DO fill-sheet-cell PARAMETERS 5. "Back" DO fill-sheet-cell PARAMETERS 7. 2. 1. 2. "B1") ABORT "Could not call-method SetData 1".error ".error ". "MajorUnit". "SetData".OLE-ERROR-DESCRIPTION(OLE-STATUS()) END // connect the graph to the spreadsheet data source #if 1 IF NOT OLE-PUT-PROPERTY(graph-id. axis-id.Caption" END IF OLE-RELEASE(chart-id) END END-PROCEDURE //fill-graph ------------------------PROCEDURE set-chart-axes PARAMETERS axis-type PIC S9(10) LOCAL FIELD axis-id PIC S9(8) IF NOT OLE-GET-PROPERTY(chart-id.Color" END DO set-chart-series-collection IF NOT OLE-PUT-PROPERTY(chart-id. "NumberFormat". "Axes". series-id. sheet-id) ABORT "Could not put-property Datasource" END #ENDIF // Get ID of first chart IF NOT OLE-GET-PROPERTY(graph-id. OLE-STATUS() END // categories 178 . axis-type) ABORT "Could not get axis id . "0") ABORT "put-property error for numberformat -" OLE-ERROR-DESCRIPTION(OLE-STATUS()) ENDIF IF NOT OLE-PUT-PROPERTY(axis-id.Item".item id . dummy-ret. 0) ABORT "Could not get charts. OLE-ERROR-DESCRIPTION(OLE-STATUS()) END // fill interior with grey IF NOT OLE-PUT-PROPERTY(chart-id. OLE-STATUS() END // series name IF NOT OLE-CALL-METHOD(series-id.Caption". 0. 0. "SeriesCollection. OLE-ERROR-DESCRIPTION(OLE-STATUS()) END IF NOT OLE-PUT-PROPERTY(axis-id. "Title.Add". 1) ABORT "put-property error for majorunit" ENDIF END-PROCEDURE //set-chart-axes ---------------------PROCEDURE set-chart-series-collection LOCAL FIELD series-id TYPE OLE-INTERFACE // IF NOT OLE-CALL-METHOD(chart-id. "Charts.". 12632256) ABORT "Could not put-property Interior. 0) ABORT "Could not get series id . "HasTitle". "SeriesCollection. "HasLegend". dummy-ret) ABORT "Could not call-method SeriesCollection. 0) ABORT "Could not put-property HasLegend" END IF NOT OLE-PUT-PROPERTY(chart-id.Color".Item".Add ". OLE-STATUS() END IF NOT OLE-GET-PROPERTY(chart-id. "DataSource". "Interior. 1) ABORT "Could not put-property HasTitle" END DO set-chart-axes parameter is -3 IF NOT OLE-PUT-PROPERTY(chart-id. chart-id. "Melbourne Balances") ABORT "Could not put-property Title. FALSE) it turns off bulk processing. dummy-ret. "SetData". When OLE-BULK-PUT is called with a zero parameter value (for example. otherwise zero is returned. "SetData". OLE-BULK-PUT() When this function is called with a non-zero parameter value (for example.class-id. 1. to populate the contents of a spread sheet).queue-size) Category Environment Runtime 6. For further information refer to the ‘OLE Code Examples’ section. If successful an advise interface ID number is returned. 179 . For further information refer to the ‘OLE Code Examples’ section. For further information refer to the ‘OLE Code Examples’ section. Syntax OLE-BULK-PUT(true-false) Category Environment Runtime 6.5 v2. This function will have no impact on Windows based implementations. 0.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. Syntax OLE-ADDREF(interface-id) Category Environment Runtime 6. dummy-ret. OLE-STATUS() END // values IF NOT OLE-CALL-METHOD(series-id.5 v3. The can be used when a large number of calls to OLE-PUT-PROPERTY are used (for example.0 and above Notes This function when used with the PRONTO-Xi Thin Clients may improve the performance on networks that have significant delay on round trip communications. "A2:A9") ABORT "Could not call-method SetData 2". For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. OLE-ADVISE-EVENT() Registers a COM object to receive events based on an outgoing class ID. "B2:B9") ABORT "Could not call-method SetData 3". TRUE) it will disable the querying of the result status for individual OLE-PUT-PROPERTY functions. Syntax OLE-ADVISE-EVENT(interface-id.IF NOT OLE-CALL-METHOD(series-id. OLE-STATUS() END IF NOT OLE-RELEASE(series-id) ENDIF END-PROCEDURE //set-chart-series-collection -------------- OLE-ADDREF() Attempts to increment the reference count for a COM object and returns TRUE (non-zero) if successful otherwise FALSE (zero).5 v2. The return status of the function will indicate if any of the put property functions have failed. 2. 0.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. If successful the interface ID number is returned. otherwise FALSE (zero) is returned. OLE-CREATE-INSTANCE() Creates an instance of a COM object with the specified class ID.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.5 v2.column.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.height. The control is created within the current active window at the specified coordinates.parameter-values) Category Environment Runtime 6.1 or above (Windows). OLE-CREATE-CONTROL() Returns an Interface ID number for the control. OLE-CALL-METHOD() Calls a method on an object interface. If successful. return-field. The return-field will contain any return value from the method.context-flag) Category Environment Runtime 6.parameter-values) Category Environment Runtime 6. return-field. Syntax OLE-CREATE-CONTROL(class-id.5 v6.width) Category Environment Runtime 6. For further information refer to the ‘OLE Code Examples’ section.5 v5. Syntax OLE-CREATE-INSTANCE(class-id. For further information refer to the ‘OLE Code Examples’ section. 6.dispatch-name.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. the function returns TRUE (nonzero). 180 . This function call will avoid the Windows ‘switch to’ screen if the user manually switches back to the controlling PRONTO-Xi screen. For further information refer to the ‘OLE Code Examples’ section. This must be specified even if the method does not return a value.OLE-CALL-INTERACTIVE-METHOD() This function call is equivalent to the OLE-CALL-METHOD() and should be used when invoking an interactive method (that is. Syntax OLE-CALL-INTERACTIVE-METHOD(interface-id.dispatch-name.row. For further information refer to the ‘OLE Code Examples’ section.0 or above (UNIX/Linux) Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. Syntax OLE-CALL-METHOD(interface-id.5 v2. a method that will potentially invoke a GUI for user interaction).5 v2. otherwise zero is returned. otherwise FALSE (zero) is returned. OLE-GET-ACTIVE-OBJECT() Returns an interface ID number for the COM object with the specified class ID if that object is currently active.5 v2.5 v2. the function returns TRUE (nonzero). Syntax OLE-ERROR-DESCRIPTION(error-status) Category Environment Runtime 6.5 v2. Syntax OLE-GET-ACTIVE-OBJECT(class-id) Category Environment Runtime 6. otherwise returns zero. If successful.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. OLE-GET-DISPATCH-ID() Gets the dispatch interface ID of a property or method.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. For further information refer to the ‘OLE Code Examples’ section. For further information refer to the ‘OLE Code Examples’ section. Syntax OLE-ENUM-RESET(interface-id) Category Environment Runtime 6.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. Syntax Category OLE-GET-DISPATCH-ID(interface-id. OLE-ENUM-RESET() Resets the enumeration cursor to the start of the collection.0 and above Notes For further information refer to the ‘OLE Code Examples’ section. otherwise FALSE (zero) is returned.prop-meth-name) Environment 181 .OLE-ENUM-NEXT() Returns the next value in the enumeration.5 v2. For further information refer to the ‘OLE Code Examples’ section. Syntax OLE-ENUM-NEXT(interface-id. OLE-ERROR-DESCRIPTION() Returns the description for the specified OLE error number.return-field) Category Environment Runtime 6. the function returns TRUE (non-zero). If successful. OLE-GET-PROPERTY() Gets a value from a property on an interface.advise-interface-id) Category Environment Runtime 6. otherwise FALSE (zero) is returned. If successful. For further information refer to the ‘OLE Code Examples’ section.value) Category Environment Runtime 6. The return-field contains the property value returned.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.despatch-name.5 v2. otherwise FALSE (zero) is returned. Syntax OLE-GET-PROPERTY(interface-id.5 v2. otherwise FALSE (zero)is returned. Syntax OLE-PUT-PROPERTY(interface-id. Syntax OLE-GET-EVENT(interface-id.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. For further information refer to the ‘OLE Code Examples’ section. and returns an event interface ID if an event is found. otherwise zero is returned. OLE-PUT-PROPERTY-BYREF() Puts a value into a property by reference on an interface. For further information refer to the ‘OLE Code Examples’ section. OLE-GET-EVENT() Gets the next event from the event queue. Syntax OLE-PUT-PROPERTY-BYREF(interface-id. the function returns TRUE (nonzero).despatch-name.Runtime 6.5 v2.0 and above 182 . return-field. the function returns TRUE (non-zero).0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.parameter-values) Category Environment Runtime 6.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.despatch-name. If successful.5 v2. If successful. For further information refer to the ‘OLE Code Examples’ section.value) Category Environment Runtime 6. OLE-PUT-PROPERTY() Puts a value into a property on an interface. the function returns TRUE (non-zero).5 v2. advise-interface-id) Category Environment Runtime 6. otherwise zero is returned. OLE-RELEASE() Decrements the reference count for the interface ID. OLE-UNADVISE-EVENT() Deregisters from event notification for the specified advise interface. the function returns TRUE (non-zero). For further information refer to the ‘OLE Code Examples’ section. Syntax OLE-UNADVISE-EVENT(interface-id.class-id) Category Environment Runtime 6.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call 183 .Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. If the class ID is found the query interface ID number is returned. Syntax OLE-RELEASE(interface-id) Category Environment Runtime 6.0 and above Notes For further information refer to the ‘OLE Code Examples’ section. otherwise FALSE (zero) is returned. For further information refer to the ‘OLE Code Examples’ section.5 v2.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section.5 v2. otherwise FALSE (zero) is returned. If successful. OLE-QUERY-INTERFACE() Queries a COM object for an interface. Syntax OLE-QUERY-INTERFACE(interface-id.5 v2.5 v2. For further information refer to the ‘OLE Code Examples’ section. Syntax OLE-STATUS() Category Environment Runtime 6. For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. OLE-STATUS() Returns the error status number for the most recent OLE call.0 and above Notes This function must be called for every interface ID allocated once the application is finished with that interface. If successful the function returns TRUE (non-zero). The resources for the interface will be deallocated if the reference count is zero. or 0 if there is no active report. For further information refer to the ‘OLE Code Examples’ section. Syntax OPERATING-SYSTEM() Category Environment Runtime 4.1 and above Notes This function does not identify operating system variations or versions. and not necessarily the type of operating system that it is running under. For further information refer to the ‘OLE Code Examples’ section. 184 . an MS-DOS version of PRONTO-RAD will return MS-DOS even if it is running under WINDOWS-NT. OLE-UNADVISE-ALL() Deregisters from all events for the COM object. OPERATING-SYSTEM() Returns the general name for the type of operating system being used. Syntax OLE-UNADVISE-ALL(interface-id) Category Environment Runtime 6.1 and above Notes The report-name parameter is optional. For example.0 and above Notes For details on the parameters for this function call refer to the ‘Common OLE() Call Parameters’ section. The value returned is based on the type of operating system that the PRONTO-RAD 4GL environment was generated for. otherwise FALSE (zero) is returned.Parameters’ section. The following operating system types may be returned:  UNIX  MS-DOS  MS-WINDOWS  WINDOWS  WINDOWS-NT  VMS Not all of these operating systems are currently supported. See Also GET-REGISTRY-VALUE() Example: IF OPERATING-SYSTEM() = 'WINDOWS' DO process-registry-call ENDIF PAGE-NO() Returns the current report page number.5 v2. Syntax PAGE-NO(report-name) Category Environment Runtime 3. If successful the function returns TRUE (non-zero). Example: PROCEDURE main REPORT 'My Report' NAME IS my-report HEADER IS header-proc PAGE ON my-report // Blank Page 1 PAGE ON my-report // Blank Page 2 MESSAGE PAGE-NO(my-report) PROCEDURE header-proc PRINT 132"-" IN COL 1 ON my-report // Result: Produces 2 blank pages first and messages "2" Example: PRINT "Date:" IN COL 21 TODAY() COL 27 "Time:" IN COL 40 TOD() COL 46 "Page No:" IN COL 58 PAGE-NO() IN COL 67 PIC ZZZ9 // Example output: Date: 31-MAY-1999 Time: 09:05:31 Page No: 24 PARAM-CNT() Returns the number of parameters passed to the current program. Due to differences between various O/S’s //it is better to pass the FILENAME() function to second. Example: //Previously useful when two programs communicated via //a flat text file. Syntax PARAM-CNT() Category Environment Runtime 3. it aborts with the MESSAGE "Incorrect parameters to " followed by the full path and filename of the program. 185 .1 and above Notes This function is not intended for general use. PID() Returns the process ID number of the currently running program.1 and above See Also GET-PARAM() Example: PROCEDURE main IF PARAM-CNT() = 0 // NB: GET-PARAM(0) is programs full path and name ABORT "Incorrect parameters to " GET-PARAM(0) ELSE DO rest-of-program ENDIF // Result: If the program is called without parameters. Syntax PID() Category Environment Runtime 3. 0) of the runtime interpreter. PROUSER-FLAGS() Returns a binary mapped value for the current user registered in the PROUSER file. or function that you are trying to use.2 IF PRONTO-RELEASE() >= 5 DISPLAY BITMAP "mypic. greater or equal Release 5. Note: Do not use #ifdef. PROSPL.STR(PID())) SPL 'sys/progb' PARAMETERS ARE ws-file-name PRONTO-RELEASE() Returns the release number (for example. statement.bmp" @5.5 ELSE DISPLAY "N/A" @5.5 #ENDIF //Format B #IF PRONTO-RELEASE_5 IF PRONTO-RELEASE() >= 5 DISPLAY BITMAP "mypic. displaying BITMAPS only became available with VER 5. For example.5 ENDIF #ELSE DISPLAY "N/A" @5. Syntax PRONTO-RELEASE() Category Environment Runtime 4.5 ENDIF #ELSE DISPLAY "N/A" @5.5 ELSE DISPLAY "N/A" @5.1 and above Notes Runtime Checking: Using this function you can determine if the currently running version of prospl supports the command.// SET ws-file-name = CONCAT('/tmp/comms'.bmp" @5. 4. It is usually safest to employ both Runtime and CompileTime checking. Example: //Compile Time and Runtime Checking //Format A #IF PRONTO-RELEASE >= 52 // ie. B) The statement to display the bitmap will only run if the runtime is Version 5 or greater. PROCMP’s) capabilities you should use the pre-processor #if PRONTO_RELEASE_5 or similar. Each bit indicates to the runtime such things as 4GL development capabilities and so on. Compile Time Checking: If you require to check the COMPILER (that is. A mismatch of Compiler To Runtime Versions can occur when software was compiled using a Version 5 Compiler is distributed to a site using a Version 4 Runtime. 186 .5 #ENDIF // Result: A) The statement to display the bitmap will only be compiled into the program if the compiler is Version 5 or greater. 1 and above Notes This function is not intended for general use.5 END-SCREEN //main -------------------------------------------------------------- REPORT-IS-XML() Returns a True/False value indicating whether the current report is being generated in XML format.Syntax PROUSER-FLAGS() Category Environment Runtime 4. Syntax REFRESH-QUICK-LINKS() Category Environment Runtime 6. Example: // // Select which Quick Links attachments to show: Parent Project or SubProject.1 default parent-job DISPLAY job-code @1. If is for system administration use only.5 v1.3 DISPLAY job-cost-description @1. be called in [Entry] mode once the key values have been entered. REFRESH-QUICK-LINKS() Enables Quick Links and refreshes the key values used.0 and above Notes This function can. // MODE md-parent-docs PROMPT 'ParentDocs' HELP "Quick Links will show Parent Project's attachments (normally shows Sub Project's attachments)" CURRENCY OBJECT like-job-cost-master LIKE job-cost-master SCREEN main ALLOWED SEARCH md-parent-docs SELECT * FROM job-cost-master ORDER BY parent-job WHEN job-code <> parent-job DATA-GRID OCCURS 22 TITLE "All Sub Projects" DETAIL IF SCREEN-MODE() = md-parent-docs GET like-job-cost-master ON INDEX job-code KEY IS parent-job ON ERROR END-ON IF REFRESH-QUICK-LINKS MESSAGE "Press Quick Link button now to view documents for Parent Project: " parent-job ELSE MESSAGE "No documents attached to Parent: " parent-job ENDIF ENDIF ACCEPT parent-job @1. 187 . for example. Full XML report. If there is no current report it will return TRUE if XML reporting is currently enabled." in col 5 SKIP REPORT SECTION FINISHED ELSE PRINT "This is a #Pnnnn (plain text) report ." in col 5 ENDIF // Start Project section // These sections will be printed for all style reports REPORT SECTION "Projects" PRINT "Show Projects" IN COL 5 REPORT SECTION "ProjectsDetail" HIDDEN PRINT "Project 1" IN COL 15 PRINT "Project 2" IN COL 15 PRINT "Project 3" IN COL 15 PRINT "Project 4" IN COL 15 REPORT SECTION FINISHED // ProjectsDetail REPORT SECTION FINISHED // Projects SKIP // Start Customer section REPORT SECTION "Customers" PRINT "Show Customers" IN COL 5 REPORT SECTION "CustomerDetail" HIDDEN PRINT "Customer 1" IN COL 15 PRINT "Customer 2" IN COL 15 PRINT "Customer 3" IN COL 15 PRINT "Customer 4" IN COL 15 REPORT SECTION FINISHED // Customer Detail REPORT SECTION FINISHED // Customer REPORT SECTION FINISHED // WholeReport REPORT FINISHED END-PROCEDURE 188 . // -------------------------------------------------------------------PAGE REPORT SECTION "WholeReport" IF REPORT-IS-XML() REPORT SECTION "Intro" SKIP PRINT "On a full-xml report.when neither // full-xml nor no-xml is defined) // full-xml // Report Type 2. // no-xml // Report Type 3. The report-name parameter is only required for named reports. otherwise FALSE (zero).3 and above Notes This function returns TRUE (non-zero) if the current report is being generated in XML format. #Pnnnn report.nothing clickable.Syntax REPORT-IS-XML(report-name) Category Environment Runtime 6. Example: PROCEDURE main REPORT "Report Types Sample" WIDTH IS 132 // -------------------------------------------------------------------// You need to re-compile this program with only one of the lines below // active at a time. // // Report Type 1. the Project and Customer Sections below are" in col 5 PRINT "collapsed into closed folders with a (+) you click to open. Basic XML report (default . 16 DETAIL ACCEPT job-code @4. FIELD ws-review-line PIC 999 MODE md-manager PROMPT "Manager" HELP IS "Maintain Project Manager" PROCESS CORRECT SCREEN main ALLOWED SEARCH ENTRY REMOVE CORRECT md-manager PRIMARY job-cost-master REVIEW OCCURS 16 NO-PROMPT-FOR-SEARCH BEFORE CLEAR DISPLAY "Project" @3. // Application Interfaces should be designed // such that all fields are highly // visible/accessible.user-id) Category Environment Runtime 5. 79 DISPLAY "Manager Name" @ws-review-line.REVIEW-ROW() Returns the absolute row number of the current review line.29 DEFAULT jcm-project-manager HELP "Enter Manager Name" WHEN SCREEN-MODE() = md-manager END-PROCEDURE //maintain-manager ---------// Result: Manager is accepted in a window on the current review.2 DISPLAY "Description" @3. otherwise it returns the failure error number.1 and above Example: FIELD ws-review-line PIC 999 // NB: REVIEW-ROW() is not required often // and should be used sparingly. 15 TO @ws-review-line.17 BACKGROUND ACCEPT jcm-project-manager @ws-review-line. REVOKE-DB-SCHEMA() Attempts to revoke access for the specified user in the schema specified by the path and returns ZERO if successful. or zero if not called within a review screen.16 IF SCREEN-MODE() = md-manager SET ws-review-line = REVIEW-ROW() DO maintain-manager SAME ENDIF END-SCREEN // ----------------------------PROCEDURE maintain-manager WINDOW @ws-review-line.0 and above 189 . Syntax REVOKE-DB-SCHEMA(path. Syntax REVIEW-ROW() Category Environment Runtime 4.2 WHEN SCREEN-MODE() NOT IN { CORRECT md-manager } SHOW-VALUE DISPLAY job-cost-description @4. 1 and above See Also MKDIR() Example: FIELD ws-err-no PIC 9(4) // IF CD(CONCAT(GET-ENV("SRC").G. // #define RGB(R.0.'/job')) MESSAGE "Found parent directory" SET ws-err-no = RMDIR('mytest') IF NOT ws-err-no 190 .G.B) \ RGB_TO_PRONTO(R.0. Syntax RGB-TO-COLOUR(number) Category Environment Runtime 6.0.B) \ rgb-to-colour((B * 256 * 256) + (G * 256) + R) PROCEDURE main LOCAL lf-colour TYPE COLOUR SET lf-colour = RGB(255.0. Syntax RMDIR(directory-name) Category Environment Runtime 4.B) #define RGB_TO_PRONTO(R. system-administration type program. It is only relevant on RDBMS systems and may be useful for a high security level.255) MESSAGE "This is blue: " lf-colour ENDIF END-PROCEDURE //main RMDIR() Attempts to remove the directory of the specified name and returns zero if successful.Notes This function is not intended for general use.0) // red IF lf-colour = RED MESSAGE "This is red: " lf-colour ENDIF SET lf-colour = RGB(0.0) // black IF lf-colour = BLACK MESSAGE "Colour number for black is " lf-colour ENDIF IF RGB(0. See Also GRANT-DB-SCHEMA() Example: SET ws-status = REVOKE-DB-SCHEMA(company-path.G.255) = BLUE SET lf-colour = RGB(0.4 and above Example: // // This program converts standard RGB colour numbers to combined // PRONTO numbers and shows the descriptive colour names.user-id) RGB-TO-COLOUR() Converts a Windows 24 bit RGB colour code into the 16 bit format used internally by the runtime. otherwise the error number. 1 and above Notes This function returns the internal value of the mode-name and can only be used in conditional expressions involving modes defined in the program. See Also MODE-NAME() Example: IF SCREEN-MODE() = ENTRY DO some-processing ENDIF Example: ACCEPT invoice-no @5. Prev. Next-Scr or Prev-Scr. See Also SCREEN-MODE() . Syntax SCREEN-MODE() Category Environment Runtime 3.1 and above Notes The SEARCH-MODE() function provides an economical way of testing whether the current screen mode is Find. Next. Syntax SEARCH-MODE() 191 . or FALSE (zero) if not currently processing a search mode. This value can be tested against mode names (which return their internal value) to determine the current screen mode. Syntax SEARCH() Category Environment Runtime 3. SEARCH-MODE() Example: //These two code fragments are functionally equivalent: IF SCREEN-MODE() IN {FIND NEXT PREV NEXT-SCR PREV-SCR} DO some-processing ENDIF IF SEARCH-MODE() DO some-processing ENDIF SEARCH-MODE() For details on this function call refer to the ‘SEARCH()’ section.MESSAGE "Success" ELSE MESSAGE "Failed to remove directory" ENDIF ELSE MESSAGE "Could not find parent directory" ENDIF // Result: If found will delete the directory $SRC/job/mytest SCREEN-MODE() Returns the internal value associated with the current screen mode.10 WHEN SCREEN-MODE() IN {ENTRY CORRECT} SHOW-VALUE SEARCH() Returns the internal value associated with the current search screen mode. Syntax SECURITY-LEVEL() Category Environment Runtime 3. Therefore. Example: IF SET-BACKGROUND-IMAGE("c:\bitmap\logo.1 and above Notes The image will not be scaled down to fit. you do not need to use the security-level function to control access to menu options. then the background image will not be displayed. Syntax SET-DATA-AREA-NAME(text) Category Environment Runtime 6.1 and above Notes This function is not intended for general use.jpg") ENDIF 192 .1 and above Example: IF SET-DATA-AREA-NAME("Test Company") ENDIF SET-BACKGROUND-IMAGE() Displays a specified background image beneath the PRONTO-Xi logo. PRONTO-Xi applications normally perform security checking via module access flags. pass a blank (spaces) image path. Syntax SET-BACKGROUND-IMAGE(image-path) Category Environment Runtime 6. Example: // Note: the following will permit a user with // a level LESS than 6 to VIEW but NOT MAINTAIN // the selling price.10 WHEN SECURITY-LEVEL() > 6 SHOW-VALUE SET-DATA-AREA-NAME() Sets the name (description) of the current data area (company). // ACCEPT selling-price @40. The OPTION declaration has a built-in security clause that suppresses the display of the menu option if the user has insufficient security.1 and above See Also SCREEN-MODE() SECURITY-LEVEL() Returns the security level (0 to 9) of the current user. To turn off the background image. If there is insufficient room to fit both the standard PRONTO-Xi logo and the specified background image. which is displayed within the title bar for the controlling PRONTO-Xi window.Category Environment Runtime 3. 1 and above Notes The return value from this function should be ignored. Syntax SET-HELP-CONTEXT(path-to-help-file. Parameters: 193 .'=') SET lf-name = SUB-STRING(text-line.1.value) Category Environment Runtime 4.context-id) Category Environment Runtime 6.(lf-col . if it contains embedded spaces or an equals sign.1 and above Notes Both name and value can be any valid alphanumeric expression. to launch when the user presses F1 (Help).lf-value) MESSAGE "Unable to set " STR-CONCAT(lf-name) " to " lf-value ENDIF END-EXTRACT // // Result: Will set all the environment variables specified in the text file SET-FUNCTION-CODE() Sets the function code to be displayed within the status bar of the controlling PRONTO-Xi window. and returns TRUE (non-zero) if successful otherwise FALSE (zero).(lf-col + 1).1)) SET lf-value = SUB-STRING(text-line.1 and above Example: IF SET-FUNCTION-CODE("M123") ENDIF SET-HELP-CONTEXT() Specifies the help file. The environment setting only affects the current program and any child programs. Syntax SET-ENVIRONMENT(name.SET-ENVIRONMENT() Sets/changes the current value of the specified environment variable to the specified value. See Also GET-ENV() Example: LOCAL lf-value PIC X(70) lf-name PIC X(30) lf-col PIC 99 lf-path-filename PIC X(150) //Assume text-file contains lines such as "TMPDIR=C:\TMP" EXTRACT text-file ALL DETAIL SET lf-col = PATTERN(text-line. for example. STR-LEN(text-line)) IF NOT SET-ENVIRONMENT(lf-name. and optionally a context ID identifying a specific help topic within the help file.value) SET-ENV(name. FALSE may be returned if the name is invalid. Syntax SET-FUNCTION-CODE(text) Category Environment Runtime 6. help-file A text string containing the name of the help file to invoke. If a full path is not specified the runtime will use the default location for PRONTO-Xi Help. If no extension is specified, then an extension of ‘.chm’ (compiled HTML) is used. context-id A number representing the marker within the help file for the current help context. If this number is zero then no help context is used. This number is only valid with Windows ‘.chm’ or ‘.hlp’ format files. Example: SCREEN main LOCAL lf-rep-code LIKE rep-code ALLOW ENTRY BEFORE DISPLAY "Use F1 key to show 'All Activities for Rep Code' ( contextsensitive help)" @10,5 DETAIL IF SET-HELP-CONTEXT("crm",64) ENDIF ACCEPT lf-rep-code @12,15 HELP "Use F1 key to show 'All Activities for Rep Code' ( contextsensitive help)" DEFAULT lf-rep-code TITLE "Rep Code Activity:" END-SCREEN //main SET-MODULE-CODE() Sets the module code to be displayed within the status bar of the controlling PRONTO-Xi window. Syntax SET-MODULE-CODE(text) Category Environment Runtime 6.1 and above Example: IF SET-MODULE-CODE("GL") ENDIF SET-REGISTRY-VALUE() Sets the specified Windows registry key to the specified value, and returns TRUE (non-zero) if successful, otherwise FALSE (zero). Syntax SET-REGISTRY-VALUE(key,value) Category Environment Runtime 6.4 and above Notes If the key ends with a slash (/ or \) it is assumed that the default value for the key is to be set. If the key does not end with a slash, the last part of the key is considered as the name of the value within the leading key. Currently only REG-SZ values are supported. See Also GET-REGISTRY-VALUE, DELETE-REGISTRY-VALUE SLEEP() Sleeps for the specified number of seconds. Syntax SLEEP(number) 194 Category Environment Runtime 3.1 and above Notes The return value from this function will ALWAYS be ZERO. Unlike the UNIX version, which can be interrupted and returns the number of seconds remaining in the countdown, the SLEEP function cannot be interrupted. As there are no plans to implement an interrupt facility, the function always counts down to ZERO. Example: IF SLEEP(60) ENDIF // Result: Process will sleep for 60 seconds Example: FIELD ws-result TYPE BOOLEAN SET ws-result = SLEEP(10) // // Result: process will sleep 10 Seconds, ws-result will ALWAYS be ZERO SPOOL-FILE-NAME() Returns the name of the current spool file created by the REPORT statement, or spaces if there is no current spool file. Syntax SPOOL-FILE-NAME() SPOOL-FILE-NAME(report-name) Category Environment Runtime 3.1 and above Notes This function allows you to display on the screen the name of the spool-file to which the report is being sent. When multiple ‘named’ reports are opened simultaneously, use the report-name parameter to identify the specific report. Example: REPORT "Customer's Transactions" DISPLAY "Spooling report to" @20,50 DISPLAY SPOOL-FILE-NAME() @20,70 //Example: Optional use of a report name for multiple 'name' reports. PROCEDURE main // // Open two 'named' reports. // REPORT "my 1st report" NAME rpt1 REPORT "my 2nd report" NAME rpt2 // // Use of this function without the report name argument. // MESSAGE "spool-file-name() function without argument returns: " SPOOL-FILE-NAME() NAME rpt1 // // Use of this function with the report name argument. // MESSAGE "Using names, 1st report is: " SPOOL-FILE-NAME(rpt1) " and 2nd report is: " SPOOL-FILE-NAME(rpt2) // Example results: 195 // // // // // The first message returns nothing, although two reports are active. That is: spool-file-name() function without argument returns: The second message returns the correct spool file names. That is: Using names, 1st report is: 05801.xml and 2nd report is: 05802.xml START-DIR-SEARCH() Searches a specified directory for files matching a specified pattern. Syntax START-DIR-SEARCH(directory,pattern) NEXT-DIR-ENTRY() FINISH-DIR-SEARCH() Category Environment Runtime 3.1 and above Notes Implementing a directory searching requires the use of three functions.  The START-DIR-SEARCH function initiates directory searching. It is passed the name of the directory to search in, and a pattern that file names must match. The pattern specified is in the same format as that used by the PATTERN() function. A directory of SPACES defaults to the current directory, and a pattern of SPACES defaults to all files. This function returns 1 (TRUE) if the directory specified exists and can be searched, otherwise it returns zero (FALSE).  The NEXT-DIR-ENTRY function returns the next file name found in the directory that matches the pattern. When no more matching file names are found in the directory, a value of spaces is returned. The file names are returned in the order that they are found in the directory, and not in any sorted order.  The FINISH-DIR-SEARCH function should be called if directory searching is finished before NEXT-DIR-ENTRY returns SPACES. It de-allocates any resources used during the directory search process. FINISH-DIR-SEARCH always returns 1 (TRUE). Example: FIELD ws-dir ws-dir-ok ws-filename ws-search-pattern ws-count PIC X(300) TYPE BOOLEAN PIC X(80) PIC X(14) PIC 99 PROCEDURE main // Sample Search patterns // SET ws-search-pattern = // SET ws-search-pattern = // SET ws-search-pattern = // SET ws-search-pattern = '^8' '8' 'l$' '0?*ml$' // // // // // Filename Filename Filename Filename END with must must must must 'ml' START with an '8' contain an '8' END with an 'l' START with 0 and // // For full search pattern rules see 'pattern' function. // SET ws-count = 0 SET ws-dir = GET-ENV("REPORTDIR") SET ws-search-pattern = '1.xml' // Find Report files whose names contain // '1.xml' // IF START-DIR-SEARCH(ws-dir, ws-search-pattern) SET ws-dir-ok = TRUE ELSE SET ws-dir-ok = FALSE ENDIF WHILE ws-dir-ok SET ws-filename = NEXT-DIR-ENTRY() 196 IF ws-filename = SPACES SET ws-dir-ok = FALSE ELSEIF ws-count >= 5 SET ws-dir-ok = FALSE IF FINISH-DIR-SEARCH ENDIF // // // // // // // // // Search exhausted - No more files or none found at all. PRONTO automatically returns memory resources allocated to search. Find no more than 5 Early break in loop. Although resources allocated will be returned at programs end, finish-dir-search returns memory resources immediately. ELSE MESSAGE "File found: " ws-filename SET ws-count += 1 ENDIF END-WHILE MESSAGE ws-count " reports were found" SYSTIME() Returns the current system time as the number of seconds since midnight January 1st, 1970. Syntax SYSTIME() SYS-TIME() Category Environment Runtime 3.1 and above Notes The PRONTO-Xi application suite of programs should not use this function. The GMT() function should be used. Use this to set both the time and date simultaneously. SYSTIME() is local time, that is, the actual system clock as modified by time zone. Thus if daylight savings applies, the return value will reflect that, SYSTIME() returns exactly what the UNIX ‘date’ command returns. Note: Due to the fact that SYSTIME() is modified by time zone, it should not be used to time and date stamp two transactions from two different time zones. See Also GMT() Example: // Assume UNIX 'date' returns // eg Wed Feb 16 2000 17:22:28 EETDT 2000 FIELD ws-date-time TYPE DATE-TIME SET ws-date-time = SYS-TIME() MESSAGE "System time is: " DATE-FROM-DATE-TIME(ws-date-time,0) TIME-FROM-DATE-TIME(ws-date-time,0) // // Example output: System time is: 16-FEB-2000 17:22:28 TIME-ELAPSED() Reduces the amount of screen output in a “Now at:” style loop, and returns TRUE (non-zero) when enough time has elapsed to display the next code on the screen. Syntax TIME-ELAPSED(interval,seconds) Category Environment Runtime 6.1 and above Notes The seconds parameters specifies the minimum elapsed time before the function returns TRUE again. The interval parameters specifies the minimum number of calls to the function before it will test for the time again. This function will not return TRUE until the minimum interval and the minimum time are reached. To initialise the internal counters for the interval and time, use TIME-ELAPSED(0,0). 197 2. Converted to seconds that is // a figure around 36000 secs.Note: The bandwidth of wide area networks can be seriously impacted by a “Now at” style loop that displays values without testing if enough time has elapsed since the last display.2 EXTRACT deb-master IF TIME-ELAPSED(100.10 ENDIF //process accountcode END-EXTRACT TIME-ZONE() Returns the difference.01 and above (implemented but not functioning in earlier versions) See Also GMT() Example: FIELD ws-num-secs-diff PIC S9(15) ws-mins PIC S9(15) ws-secs PIC S9(15) ws-hours PIC S9(13)V99 // // For us here in South Eastern Australia // the difference between GMT and EETDT should // be some Ten Hours.1 and above Example: PRINT "Time:" IN COL 40 TOD() COL 46 // // Result: For example. Syntax TIME-ZONE() Category Environment Runtime 5. in seconds. Time: 09:05:31 198 . Syntax TOD() Category Environment Runtime 3.00 0 0 TOD() Returns the time of day as the number of seconds since midnight today. between GMT and the local time zone. 2) DISPLAY accountcode @10. Example: DISPLAY "Now at:" @10. // SET ws-num-secs-diff = TIME-ZONE() // MESSAGE "Difference in Seconds between GMT and Local Timezone is " ws-num-secs-diff // SET ws-hours = INTEGER(ws-num-secs-diff / 3600) SET ws-mins = FRACTION(ws-num-secs-diff / 3600) * 60 SET ws-secs = FRACTION(ws-num-secs-diff / 60) * 60 MESSAGE "Which is Hours Mins Secs: " ws-hours ws-mins ws-secs // // Result: Difference in Seconds between GMT and Local Timezone is -36000 Which is Hours Mins Secs: -10. TODAY() Returns today’s date as a date value. Syntax TTY() Category Environment Runtime 3. Syntax TODAY() Category Environment Runtime 3. Provides a method of identifying a particular port number.1 and above Example: PRINT "Date:" IN COL 21 TODAY() COL 27 "Time:" IN COL 40 TOD() COL 46 "Page No:" IN COL 58 PAGE-NO IN COL 67 PIC ZZZ9 // // Result: For example. Example: //Assuming user accesses the Server via Port 59 MESSAGE TTY() // // Result: 59 UID() Returns the user ID of the current user. Date: 31-MAY-1999 Time: 09:05:31 Page No: 24 TRANSACTION-ACTIVE() Returns a positive value when an application specified transaction is in progress. Syntax UID() Category Environment Runtime 3. A negative value is returned to indicate a runtime generated automatic transaction. is not working across a network.1 and above Notes This function is not intended for general use. that is. Group ID and User ID’s are set up when first registering a user for 199 . Syntax TRANSACTION-ACTIVE() Category Environment Runtime 6.5 v2.0 and above Example: IF NOT TRANSACTION-ACTIVE() TRANSACTION BEGIN ENDIF TTY() Returns the current user’s terminal number.1 and above Notes Group Code. It can only be relied upon when the user has a direct port connection to the computer. Example: MESSAGE "Your Group Code is " USER-GROUP() MESSAGE "Your Group ID is " GID() MESSAGE "Your User ID is " UID() USER-GROUP() Returns the single character defining the user’s group. Example: //RETURN VALUES // -8 Down // -7 Up // -10 Left // -9 Right // ascii-num('W') + 32 = 'W' was typed on the Keyboard // -20 Click 200 . Notes This function is not intended for general use. This function can be used in conjunction with the MOUSE-ROW() and MOUSE-COLUMN() functions to define ‘Hot Spots’ on the screen. See PROADMIN (Enter User Details).activation) Category Environment Runtime 4. Syntax VALID-ACTIVATION-KEY(key.PRONTO-Xi. Example: MESSAGE "Your Group Code is " USER-GROUP() MESSAGE "Your Group ID is " GID() MESSAGE "Your User ID is " UID() VALID-ACTIVATION-KEY() Returns a True/False result indicating whether the specified key and activation string are valid for this installation. Syntax WAIT-FOR-INPUT() Category Environment Runtime Not supported in versions of PRONTO-Xi (runtime release 6. Group ID and User ID’s are set up when first registering a user for PRONTO-Xi.1 onwards). that is. See Also CHECK-AUTH() WAIT-FOR-INPUT() Pauses until the user presses a key or clicks the mouse button. an alternative method of determining where the mouse was clicked may be provided in a future release. Syntax USER-GROUP() Category Environment Runtime 3. areas in which specific actions are to take place if a mouse click is detected within that area. See PROADMIN (Enter User Details). Due to the requirement to place this function in a loop.1 and above Notes This function is reserved for future use.1 and above Notes Group Code. 10 TO @12.5 BACKGROUND SET ws-mouse-mode = 1 BOX @8.50 WHILE ws-mouse-mode SET ws-mouse-mode = WAIT-FOR-INPUT() IF ws-mouse-mode = -20 // Click // Lets ascertain where they clicked SET ws-msg = "Please Click INSIDE a Box" if MOUSE-ROW() BETWEEN 8 AND 12 IF INTEGER(MOUSE-COLUMN() / 10) = 1 SET ws-msg = "BOX ONE" ELSEIF INTEGER(MOUSE-COLUMN() / 10) = 2 SET ws-msg = "BOX TWO" ELSEIF INTEGER(MOUSE-COLUMN() / 10) = 3 SET ws-msg = "BOX THREE" ELSEIF INTEGER(MOUSE-COLUMN() / 10) = 4 SET ws-msg = "BOX FOUR" ENDIF ENDIF ELSEIF ws-mouse-mode IN { -1 .40 BOX @8.20 TO @12.30 BOX @8. 0 } EXIT ELSE SET ws-msg = CONCAT("Mouse Mode = " STR(ws-mouse-mode)) ENDIF DISPLAY ws-msg @5.40 TO @12.Left-Click in a Box or Right-Click/ESC to EXIT" @3.20 BOX @8.5 BACKGROUND END-WHILE String Handling Functions PRONTO-RAD supports the following string handling functions: ASCII-CHAR() LINE-NO() SIZE-OF() ASCII-NUM() LOWERCASE() STRING-CONCAT() CONCAT() NUM() STR-LEN() FIND-PARAMETER() OCCURRENCE() SUB-STRING() FORMAT-PICTURE() PARAM-TEXT() UPPERCASE() FSTR() PATTERN() VALID-NUMBER() IDX() RESERVED() ZSTR() LEFT-JUSTIFY() RIGHT-JUSTIFY() ASCII-CHAR() Returns the alphanumeric character associated with ASCII number in the printable range of ASCII characters.30 TO @12.// // // -1 0 -23 Right-click or Esc Return Double-click FIELD ws-mouse-mode PIC S999 ws-msg TYPE STRING PROCEDURE main WINDOW DISPLAY "Mouse Trap . 201 . 1 and above Example: PRINT ASCII-CHAR(65) IN COL 1 // // Result: 'A' is printed ASCII-NUM() Returns the ASCII value of the first character in string.1 and above Notes This function is not intended for general use. trailing spaces are omitted from the output string if the field is defined as type string. If longer concatenated strings are required. the maximum length of the calculated alpha field is limited to 40 characters. use this function in the RPT report generator instead..i. This function can be used to test for the presence of non-printable characters in a string."World") // // NB: A String such as this would not normally // be encountered in PRONTO-Xi unless it were // through interfacing to other Systems.Syntax ASCII-CHAR(ascii-num) Category String Runtime 3.. Example: FIELD ws-a PIC X(15) ws-b PIC X i PIC 99 SET ws-a = CONCAT("Hello". Syntax CONCAT(string1. All character positions in alphanumeric fields are included in the output string.ASCII-CHAR(10). However.string2.ASCII-CHAR(13).) Category String Runtime 3. When using this function in an SQL report created using the LST report generator.. including any trailing spaces. 202 . Syntax ASCII-NUM(string) ASCII(string) ASC(string) Category String Runtime 3.i) IF ASCII-NUM(ws-b) NOT BETWEEN 32 AND 127 MESSAGE "String contains characters outside range" BREAK ENDIF END-FOR // // Result: messages "String contains characters outside range" CONCAT() Creates a new string or alphanumeric field by joining together any number of strings or alphanumeric fields.1 and above Notes This function yields a different result depending on whether the input fields are defined as type string or as type alphanumeric. // FOR i = 1 TO STR-LEN(ws-a) SET ws-b = SUB-STRING(ws-a. The value can be of any data type.1 and above Notes All valid picture strings can be used.1 and above Notes The comparison performed is not case-sensitive. Syntax FORMAT-PICTURE(value. For example: SET full-name = CONCAT(STR-CONCAT(first-name). Syntax FIND-PARAMETER(string) Category Environment Runtime 4. but must be compatible with the specified 203 .STR-CONCAT(sur-name))) // // Result: full-name = "TOM BROWN" FIND-PARAMETER() Returns the parameter number of the parameter matching the specified string.See Also STR-CONCAT() Example: FIELD first-name PIC X(20) sur-name PIC X(30) full-name PIC X(50) SET first-name = "TOM" SET sur-name = "BROWN" SET full-name = CONCAT(first-name.picture) Category String Runtime 4. Example: //PROGRAM A: PROCEDURE main SPL 'B' PARAMETERS ARE '-exec' 'FINDME' 'findme' //PROGRAM B: PROCEDURE main MESSAGE FIND-PARAMETER("FINDME") MESSAGE FIND-PARAMETER("-exec") MESSAGE FIND-PARAMETER("findme") // // Result: Outputs '2' '1' '2' FORMAT-PICTURE() Returns an alphanumeric string containing the value formatted using the specified picture string. Example: //If we define the fields as TYPE string // Result: full-name = "TOMBROWN" Example: // If STR-CONCAT() is used instead of CONCAT() in the // above example it will eliminate first-name's // trailing spaces in the output field. 17 spaces appear in full-name // after the word "TOM" corresponding to the full // length of the field first-name. so uppercase and lowercase parameters are considered the same. or zero if there is no matching parameter.sur-name) // Result: full-name = "TOM BROWN" // In this example. The picture string is specified as an alphanumeric expression." ". picture string. Example: SET ws-text = FORMAT-PICTURE(gl-trans-date,"ddmmmyyyy") FSTR() Like the STR() function, returns a string representation of the numeric argument, however this function lets you format the resulting string by specifying the number of integer places and the number of decimal places. Syntax FSTR(number,integer-places,decimal-places) Category String Runtime 3.1 and above Notes The string returned is padded so that the number of integer and decimal places are always the same. Leading spaces precede the first integer digit. The ZSTR() function can be used if leading zeros are required. A common use of FSTR() is to right-justify a numeric value in an alphanumeric field. For example, suppose you are using the SERIAL statement to increment the next available invoice number, while the invoice number is stored on each invoice as an alphanumeric field. The SIZE-OF() function gives you an easy way of specifying the number of integer places required to right-justify the number. Example: FIELD ws-num PIC 9(8)V9999 ws-text PIC X(10) SET ws-num = 1234.9876 SET ws-text = FSTR(ws-num,6,2) // // Result: ws-text = "__1234.99" Example: SET invoice-no = FSTR(serial-invoice,SIZE-OF(invoice-no),0) IDX() Returns one of the specified values given the value of index. For example, value2 would be returned if index contained 2. Syntax IDX(index,value1,value2,...) Category Environment Runtime 3.1 and above Notes The values can either be all numeric or all alphanumeric. index values less than one will return the first value. index values greater than the number of values will return the last value. Example: FIELD lf-pos PIC 99 lf-tag PIC X(3) lf-i PIC 99 text-line PIC X(60) // // Parse a text line for each of // three predefined TAGS in turn. // SET text-line = 'Ensure that you +B+ indent procedures +B+' FOR lf-i = 1 TO 3 // Number of tags to check SET lf-tag = IDX(lf-i,'+W+','+B+','+K+') SET lf-pos = PATTERN(text-line,lf-tag) 204 IF lf-pos MESSAGE ELSE MESSAGE ENDIF END-FOR // Result: "+W+ "+B+ "+K+ lf-tag " Tag found" lf-tag " Tag NOT found" Tag NOT found" Tag found" Tag NOT found" LEFT-JUSTIFY() Left justifies the specified string, which can be used to remove any leading spaces in the string. Syntax LEFT-JUSTIFY(string) Category String Runtime 3.1 and above Example: FIELD ws-new-ref PIC X(20) ws-old-ref PIC X(16) SET ws-old-ref = ' 129AB-100.01' SET ws-new-ref = LEFT-JUSTIFY(ws-old-ref) MESSAGE "OLD REF is:" ws-old-ref MESSAGE "NEW REF is:" ws-new-ref // // Result: OLD REF is: 129AB-100.01 NEW REF is:129AB-100.01 LINE-NO() Returns the current report line number, or zero if there is no active report. Syntax LINE-NO() Category Environment Runtime 3.1 and above Example: SET lf-new-page-reqd = TRUE EXTRACT invoice-detail-to-print DETAIL IF (lf-new-page-reqd) OR (LINE-NO() > ws-reqd-num-lines-per-invoice) PAGE SKIP TO reqd-start-line ENDIF DO print-invoice-details END-EXTRACT // // Result: Skips to required new Page and Line number as defined by User LOWERCASE() Returns the equivalent string with all alphabetic characters in lowercase. Syntax Category LOWERCASE(string) String 205 Runtime 3.1 and above See Also UPPERCASE() Example: FIELD ws-new-ref PIC X(20) ws-old-ref PIC X(20) SET ws-old-ref = 'ALL THIS WAY NOW' SET ws-new-ref = LOWERCASE(ws-old-ref) MESSAGE ws-old-ref MESSAGE ws-new-ref // // Result: ALL THIS WAY NOW all this way now NUM() Returns the numeric value of the value stored in a specified alphanumeric or string field. Syntax NUM(string) Category String Runtime 3.1 and above Notes This function allows an alphanumeric or string field to be used in an arithmetic expression. It can also be used to convert a numeric parameter, passed to a program as an alphanumeric field, back to its original numeric value. Example: FIELD ws-this-weeks-jackpot PIC X(10) // Assuming Prize Pool = $1000 // and you key in $420 for this week ACCEPT ws-this-weeks-jackpot @5,5 MESSAGE "Total Prize Pool = " total-prize-pool + NUM(ws-this-weeks-jackpot) // // Result: Total Prize Pool = $1420 Example: FIELD ws-report-no PIC 999 SET ws-report-no = NUM(GET-PARAM(3)) OCCURRENCE() Returns the occurrence (number of elements in the array) of the specified field. Syntax OCCURRENCE( field ) Category Arithmetic Runtime 3.1 and above Notes This function is useful for controlling loops that process each element of an array in turn. Example: FIELD month-sales PIC S9(13)V99 OCCURS 12 FOR i = 1 TO OCCURRENCE(month-sales) PRINT month-sales[i] IN COL (i * 10 - 10) END-FOR // // Result: The loop will process from 1 to 12 months Example: ACCEPT month-to-process @5,5 ALLOWED 1 TO OCCURRENCE(month-sales) 206 // // Result: A value between 1 and 12 may be entered PARAM-TEXT() Allows parameter substitution on the specified text. Syntax PARAM-TEXT (text,params) Category String Runtime 6.7 and above See Also MESSAGE, MESSAGE-BOX The text can contain the following substitution markers.  <<BR>> - Causes a break (new line) when used as text in a MESSAGE-BOX statement.  <<Pn>> - Substitutes the value of parameter n. For example, <<P2>> specifies parameter 2. Examples: PROCEDURE param-text-example FIELD lf-account LIKE accountcode lf-balance TYPE numeric lf-msg TYPE STRING PIC X(300) // // Example 1 // SET lf-account = "GALVANIC" SET lf-balance = 7800 MESSAGE PARAM-TEXT ("Customer: <<P1>> has a balance of <<P2>>", lf-account, lf-balance) // // Example 2 : Note: The text must be entered as a quoted literal on a sin // gle line and so currently cannot exceed 296 characters due to a pre// processor limit. // SET lf-msg = PARAM-TEXT("Customer : <<P1>> currently has a balance of <<P2>> <<BR>>but please understand that this will not be correct if there were more transactions <<BR>>after the server went down at <<P3>> on <<P4>>.", lfaccount,lf-balance,TOD(),TODAY()) MESSAGE-BOX lf-msg END-PROCEDURE //param-text-example PATTERN() Tests whether the specified character pattern is present in the specified text string, and returns the character position of the pattern in the string if the pattern is present, otherwise returns zero (0). Syntax PATTERN(text,pattern) Category String Runtime 3.1 and above The pattern can contain the following regular expression pattern matching characters. Character Description ^ Start of string/field. For example: PATTERN(ws-text,'^abc') matches ‘abc’ only if it occurs at the start of ws-text. 207 '~abc') matches ‘abc’ only if it occurs at the start of ws-text. ? Single character wildcard.'abc$') matches ‘abc’ only if it occurs at the end of ws-text.spl") Note: ‘*’ by itself cannot be relied upon as a pattern matching character. For example: PATTERN(ws-text.[] Find character in specified set. $ End of string/field.ws-pat) MESSAGE "YES" ELSE MESSAGE "NO" ENDIF // // Result: when ws-text = "checky this" // when ws-text = "cheeeky this" // when ws-text = "chucky this" // when ws-text = "cheesy this" Example: LOCAL FIELD lf-text PIC X(10) // SET lf-text = 'TEST1. B or C. \ Escape the following special character.'file??01') ?* Multi-character wildcard. For example: PATTERN(ws-text. Example: FIELD ws-pat TYPE STRING PIC X(10) ws-text PIC X(20) SET ws-pat = 'ch?*ky' // Find 'ch' followed by ANY Number of // characters followed by 'ky' // IF PATTERN(ws-text.'[~ABC]') matches any character other than A.002' IF PATTERN(lf-text. performs the same function as the ^ character.'. Note: Type string is assumed. For example: PATTERN(ws-text. For example: PATTERN(ws-text."\?") matches an actual question mark character in ws-text. ~ When used as the first character in a character set. negates the character set.') MESSAGE "Text field contains a DOT" 208 YES YES YES NO . Otherwise will test for the pattern at the actual end of the field. Matches any number of characters. For example: PATTERN(ws-text."?*. For example: PATTERN(ws-text. space. or numeric character in ws-text. When used as the first character in the pattern.'[A-Za-z 0-9]') matches an alphanumeric. For example: PATTERN(ws-text. Syntax RESERVED(word) Category String Runtime 3. lf-word. 'extract'. “SET”).') IF lf-pos MESSAGE "Text field contains a DOT at position " lf-pos ENDIF // // Result: Text field contains a DOT at position 6 Example: LOCAL FIELD lf-text PIC X(30) // //Testing explicitly for when the patterned text is at //BEGINNING of the field. otherwise 0. "'") " is NOT a reserved word" ENDIF END-FOR //RESULT: // // // 'find' is a reserved word 'dentist' is NOT a reserved word 'extract' is a reserved word 'teeth' is NOT a reserved word RIGHT-JUSTIFY() Returns a string of the specified size.ENDIF // // Result: "Text field contains a DOT" Example: LOCAL FIELD lf-pos PIC 9(4) lf-text PIC X(10) // SET lf-text = 'TEST2. with the specified string right justified within it.1 and above Example: LOCAL lf-word PIC X(30) lf-i PIC 99 // Check these 4 words to see if they are reserved for use by PRONTO-Xi FOR lf-i = 1 TO 4 SET lf-word = IDX( lf-i .'^abc’) MESSAGE "YES abc is at start of field" ELSE MESSAGE "NO abc is NOT at start of field" ENDIF // RESULT: YES abc is at start of field RESERVED() Returns 1 if the word is a PRONTO-RAD 4GL reserved word (for example.002' SET lf-pos = PATTERN(lf-text.'. 'dentist'. Syntax RIGHT-JUSTIFY(string.size) 209 . "'") " is a reserved word" ELSE MESSAGE STR-CONCAT("'". lf-word.'find'. // SET lf-text = 'abc is at the beginning of the field' IF PATTERN(lf-text. 'teeth') IF RESERVED(lf-word) MESSAGE STR-CONCAT("'". string2. If longer concatenated strings are required. See Also LEFT-JUSTIFY() Example: FIELD ws-no PIC X(8) // ACCEPT ws-no @5.5 PAUSE // Result: Assuming 453 is entered 453 453 453 SIZE-OF() Returns the total storage size of the specified alphanumeric field..5 SET ws-no = RIGHT-JUSTIFY(ws-no.Category String Runtime 3..5 SET ws-no = RIGHT-JUSTIFY(ws-no.0 Notes When using this function in an SQL report created using the LST report generator.SIZE-OF(ws-no)) DISPLAY ws-no @7. FIELD ws-text PIC X(10) SET ws-text = "ABCDEFGHIJ" MESSAGE "Chars 8 to 10 : " SUB-STRING(ws-text. use this function in the RPT report generator instead. or the STRING statement.5) DISPLAY ws-no @6. See Also CONCAT() Example: FIELD ws-first-name PIC X(20) ws-surname PIC X(30) 210 . for example the SUB-STRING() function. Example: // Obtain data from the last 3 character // positions at the end of an alpha field.) Category String Runtime 4. the maximum length of the calculated alpha field is limited to 40 characters. that is. SIZE-OF(ws-text). except all parameters are treated as type string. Syntax STR-CONCAT(string1. trailing blanks are always ignored.1 and above Notes This function avoids hard-coding the length of an alphanumeric field in string manipulation operations.2..SIZE-OF(ws-text)) // // Result: "Chars 8 to 10 : HIJ" STR-CONCAT() Similar to the CONCAT() function. Syntax SIZE-OF(field) Category String Runtime 3.1 and above Notes To right-justify an alphanumeric field use SIZE-OF() to control the output size. Returns a character string consisting of the from character position to the to character in the string string.1 and above Example: FIELD ws-text PIC X(20) SET ws-text = "Hello World" MESSAGE "String Length is " STR-LEN(ws-text) // // Result: String length is 11 SUB-STRING() Creates a new alphanumeric field by extracting the characters in the source string from the from character position to the to character position.to) Category String Runtime 3. STR-LEN(string) Syntax Category String Runtime 3.1. UPPERCASE(string) Syntax Category String Runtime 3.ws-full-name PIC X(50) SET ws-first-name = "TOM" SET ws-surname = "BROWN" SET ws-full-name = STR-CONCAT(ws-first-name.1 and above Notes From and to can be specified by any numeric expression. Example: FIELD ws-text PIC X(20) ws-name PIC X(30) SET ws-name = "DAVID BROWN" SET ws-text = SUB-STRING(ws-name. the total size less any trailing spaces/blanks. that is.from.1 and above See Also LOWERCASE() Example: FIELD ws-new-ref PIC X(20) ws-old-ref PIC X(20) SET ws-old-ref = 'all this way now' SET ws-new-ref = UPPERCASE(ws-old-ref) MESSAGE ws-old-ref MESSAGE ws-new-ref // Result: all this way now ALL THIS WAY NOW 211 .5) // // Result: ws-text = "DAVID" UPPERCASE() Returns the equivalent string with all alphabetic characters in uppercase.ws-surname) // // Result: ws-full-name = "TOMBROWN" STR-LEN() Returns the length of the specified string. Syntax SUB-STRING(string. b Set a breakpoint at statement .bt Set temporary breakpoint . Syntax VALID-NUMBER(string) Category String Runtime 4.q Quit the debugger .c Clear breakpoint at statement . See Also NUM() Example: FIELD ws-no PIC X(8) ACCEPT ws-no @5. decimal-places ) Category String Runtime 3.6. 0 otherwise.9876 SET ws-text = ZSTR(ws-num. integer-places.ca Clear all breakpoints set .g Go .start/continue execution . Syntax ZSTR( number.2) // // Result: ws-text = "001234.cs Clear all object/screen counts 212 . except returns leading zeros rather than leading spaces.VALID-NUMBER() Returns 1 if the string contains a valid number.99" Debugger Commands Summary The following commands are supported in the debugger line of the F9 (Session Information) window: .1 and above See Also FSTR() Example: FIELD ws-num PIC 9(8)V9999 ws-text PIC X(10) SET ws-num = 1234.5 HELP "Enter the Engine Serial Number" DEFAULT ws-no VALIDATIONS IF NOT VALID-NUMBER(ws-no) OR NUM(ws-no) <= 0 MESSAGE "The Engine Serial Number must " "consist of NUMBERS only" RE-ENTER OPTIONAL ENDIF END-VALIDATIONS PAUSE ZSTR() Performs the same function as the FSTR() function.1 and above Notes This should be used in conjunction with the NUM() function to check the validity of numbers stored as strings. SPACE/SPACES: Note: To cater for its various uses.wt field <op> <var> Set temporary watch on a field .t Give a procedure trace back .lf <prefix> List fields defined .log is created in the home directory. Redisplay current statement <field-name> Display current value of field <field-name>=<value> Set field to value specified PRONTO-RAD 4GL Predefined Values YES = “Y” NO = “N” TRUE =1 FALSE =0 ZERO =0 SPACE/SPACES Empty (null) string .tf Turn on/off the program trace file (create/truncate). SPACE/SPACES is defined as type STRING which ignores trailing spaces. A file called pgmname.ls <prefix> List screens/menus/procedures defined .m Show the current screen mode .lb List all breakpoints set .s Step/execute <n> statements <n>. Perform last command again <screen-name> Display first statement for screen <screen-name>+<n> Display statement <n> for screen <down-arrow> Display next statement <up-arrow> Display previous statement +<n> Move forward <n> statements -<n> Move backwards <n> statements <n> Go to statement <n> ..lw List all watches set .z field Clear watch on a field .za Clear all watches set <n>.w field <op> <var> Set a watch on a field . 213 .la <prefix> List object access statistics .sp Step over procedure/statement .string of zero length.lo <prefix> List objects defined & status .e Show the escape flag value . .tfa Turn on/off the program trace file (create/append) . a watch is tripped or termination of the program.Since SPACE or SPACES is a string of zero length.b. lf-string will still contain the value “example_string_only” To remove the underscores.op? files) using single and procedural step disassembly.lf-i. the F2 (Help) screen will be displayed first. lf-string will contain the value “example string only”.lf-i.lf-i) = "_" STRING lf-string REPLACING SPACES AT lf-i ENDIF END-FOR After this code.lf-i) = "_" STRING lf-string REPLACING lf-help-string AT lf-i ENDIF END-FOR After this code. outlining the following commands: Command Description . lf-string will contain the value “example string only”. a 4GL program (*. To use the 4GL Debugger. it cannot for instance be used in the string command to replace characters with blanks.c) text #undef NAME #ifdef NAME #ifndef NAME #if CONSTANT_EXPRESSION #else #endif PRONTO-RAD 4GL Debugger The PRONTO-RAD 4GL Debugger provides line oriented debugging of operations tables (*. 214 . Alternatively: LOCAL FIELD lf-help-string PIC X // SET lf-help-string = SPACES SET lf-string = "example_string_only" FOR lf-i = 1 TO STR-LEN(lf-string) IF SUB-STRING(lf-string.spl file) must be compiled using the ‘-d’ option of the compiler (procmp). use “ ” as the replacing value instead of SPACES: SET lf-string = "example_string_only" FOR lf-i = 1 TO STR-LEN(lf-string) IF SUB-STRING(lf-string. Pre-Processor Commands Summary #include "filename" #define NAME string #define NAME(a.lf-i. When commencing a program that has been compiled with debug. For example: SET lf-string = "example_string_only" FOR lf-i = 1 TO STR-LEN(lf-string) IF SUB-STRING(lf-string.g Go .start/continue execution Begin or continue normal execution of the program until either a breakpoint is reached.lf-i) = "_" STRING lf-string REPLACING " " AT lf-i ENDIF END-FOR After this code. b’ command. then mark the line with a breakpoint.w field <op> <var> Set a watch on a field Watch a field (including local fields) and optionally apply an operation. This can be done at any point within a program. . .w’ command. . Any open trace file is automatically closed. Setting a watch on a local field can only be done from within the procedure that the local field comes into scope.b Set a breakpoint at statement Set a breakpoint at the currently displayed statement.s Step/execute <n> statements If <n> is omitted. Once a temporary breakpoint has been reached by the Debugger it is removed from the breakpoint table. .cs Clear all objects/screen counts Reset all object/screen counts back to zero.w field <> value Same as previous statement.q Quit the Debugger The program is terminated. . that procedure is also stepped into. Once the local field goes out of scope (exited the procedure) the watch entry for the local field is removed.w field >= value Watch until the field is greater than or equal to the specified value. 215 . . the default is to step/execute one statement at a time.w field < value Watch until the field is less than the specified value. .w field <= value Watch until the field is less than or equal to the specified value. If the current or any of the next <n> statements is a procedure.w field ! = value Watch until the field is not equal to the specified value..w field = value Watch until the field equals the specified value. To set a breakpoint at other than the current statement.w field > value Watch until the field is greater than the specified value.z field Clear watch on a field As per the ‘. . Use the Up/Down arrow keys until the desired statement is displayed.wt field <op> <var> Set temporary watch on a field . .c Clear breakpoint at statement The correct statement must first be displayed before the breakpoint can be deleted. .ca Clear all breakpoints set The command can be issued at any point within a program. . .bt Set temporary breakpoint As per the ‘. Once a temporary watch has been triggered by the debugger it is removed from the watch table. . . For example: . The name of the field must be typed exactly as it appears within the program. optionally key in the name of the procedure where the statement resides.za Clear all watches set This command can be issued at any point within a program. . <n>.w field Watch the field until it changes. this command will work like the ‘. These statistics can be reset to zero at any point using the ‘.log (where program is the name of the currently executing file). it will be appended to.lf <prefix> List fields defined This command will display a full screen listing of all the fields used by the program and their current value. . The status can be one of the following: OPEN The file is open. . The trace file will be automatically created.s’ command. .sp Step over procedure/statement If <n> is omitted the default is to step over/execute one statement at a time. FILE-LCK The file is locked. Optionally a prefix can be supplied to list only those objects beginning with that prefix. If the program is currently in a procedure that contains local fields those fields are displayed first preceded by their current procedure name. These statistics can be reset to zero at any point by using the ‘.cs’ command. Optionally a prefix can be supplied to list only those fields beginning with that prefix. The file will be automatically closed if the program terminates or reaches the end of execution. . This is to distinguish local fields from global fields of the same name.ll List loaded component libraries This command will display a full screen listing of all the loaded component libraries. CLOSED The file is closed. The file will be automatically closed if the program terminates or reaches the end of execution.lo <prefix> List objects defined and status This command will display a full screen listing of all objects and their current status in the program. .tf Turn on/off the program trace file (create/truncate) Commence or terminate (from the current statement) a program trace. . called ‘program’. The trace file will reside in your home directory. .t Give a procedure trace back This command will display a full screen listing of all the procedures called since the commencement of the program in reverse order (that is. If it already exists.la <prefix> List object access statistics This command will display a full screen listing of all the objects used by the program and the current number of reads/inserts/updates and deletes performed on those objects.<n>.cs’ command. ‘main’ displayed last). IDX-n The index ‘n’ has been used to access the file (C-ISAM only).tf’ command. . Optionally a prefix can be supplied to list only those objects beginning with that prefix.tfa Turn on/off the program trace file (create/append) As per the ‘. REC-LCK A record is presently locked in the file. If the current or any of the next <n> statements are not procedures. it will be truncated back to zero bytes. If it already exists. The trace file will be automatically created.ls <prefix> List screens/menus/procedures defined This command will display a full screen listing of all the procedures used by the program and the number of times a procedure has been accessed. Optionally a prefix can be supplied to list only those procedures beginning with that 216 . CURR-REC A record is current.  The current value of the field.  The current value of the watch. The window shows the extraction order. 217 . . it only displays it.  Optionally any operator used to set the watch.is Toggles the SELECT information window on/off. disassembled-line $ . For example.m Show the current screen mode The mode of the current procedure is displayed. [Correct]. used to process the SELECT operation. This does not execute the next statement. subsequent ‘. indexes. disassembled-line The disassembled line where the breakpoint is set. Note: This may or may not be the last statement executed by the program. . When set to on. Each line in the listing takes the following form: procedure+number. List all watches set This command will display a full screen of all watches currently active in the program. <screen-name> Display first statement for screen The name of any defined procedure can be entered here. the SELECT information window will be displayed each time the 4GL runtime processes a new SELECT statement within the application. sorting and joins etc. Once a watch has been tripped. Perform last command again Any of the above ‘.lb List all breakpoints set This command will display a full screen listing of all breakpoints currently active in the program. [Remove] or a user-defined mode. these field will be displayed preceded by their current procedure name.lq List last SQL command/query generated (RDBMS versions only) This will display the last SQL command executed by the RDBMS. number The offset line number from the start of the procedure.e Show the escape flag value This escape value will be either TRUE or FALSE. <screenname>+<n> Display statement <n> for screen <down-arrow> Display next statement The name of any defined procedure and offset can be entered here. it only displays it.’ commands will be repeated. [Entry]. . . +<n> Move forward <n> statements Move the currently displayed line forward by <n> statements. This is to distinguish local fields from global fields of the same name. . <up-arrow> Display previous statement This does not execute the next statement.lw’ listings will also show on the prompt line the last statement in the program to have tripped the watch.lw procedure The procedure associated with the breakpoint. If the program is currently in a procedure that contains local fields with watches.prefix. Each line in the listing will consist of:  The field with the active watch. . Redisplay current statement Redisplay the current statement that will be executed next.). disassembled-line The disassembly of the current statement being executed. a few points should be made. Commands are entered on the help line at the ‘$’ prompt. <n> Go to statement <n> Move to the specified statement.-<n> Move backwards <n> statements Move the currently displayed line backward by <n> statements. String. STR(x)) PAUSE SET x = x + 1 END-WHILE The disassembly and trace-file output will always show the latter statements. 218 . one anomaly should be pointed out. Field name Any command that makes reference to a field can also mean a local field (only when the local field is in scope). <fieldname>=<value> Set field to value specified The name of the field must be entered in full. <field-name> Display current value of field The name of the field must be entered in full. STR(x)) PAUSE END-FOR is compiled as: SET x = 1 WHILE x < = 10 MESSAGE CONCAT('x= '. References to field subscripts should be made as per the 4GL language that is to immediately follow the field name by an opening square bracket. The FOR statement being a single statement is compiled into an operations table as three separate statements. Firstly. When assigning alphanumeric values to fields. comments lines are not stored in an operations table in any way and are consequently never seen whilst debugging a program. . which may optionally include a field ‘occurs’ subscript. The value assigned to the field must also match its data type (Numeric. all macro (#define) functions and constants are expanded during compile-time and stored in-line in the operations table. Secondly. Whilst stepping through each line of code the ‘$’ prompt takes the following form: procedure+number: disassembled-line $ procedure The current procedure being executed. the subscript value and a closing square bracket. Because the 4GL Debugger does not show source code directly from the corresponding SPL file of an operations table. number The offset line number from the start of the procedure. consequently the debugger has no knowledge of these directives. Some clarifications should also be made to commands with regards to the following: Procedure name Any command that makes reference to a procedure name can also mean a screen or menu procedure. etc. Date. Consider the following: FOR x = 1 TO 10 MESSAGE CONCAT('x= '. Lastly. they should always be enclosed in single or double quote marks. The ‘Error Macros’ sections lists these common error numbers that can be relied upon regardless of the database in use. the PRONTO-Xi runtime will automatically map certain database specific errors to common error numbers. Using the same example. the PRONTO-Xi runtime will always return error EDUPL (100) for a duplicate record error. regardless of the database used.w dept-total[2] If a field containing an ‘occurs’ range is referenced by a command without specifying a subscript. Database Error Numbers The various databases used by PRONTO-Xi each return different error numbers for failed operations. the subscript will default to ‘1’. For example. the PRONTO-Xi runtime shows the database specific error numbers as negative error numbers. each database returns a different error number if it encounters a duplicate record on a unique key. For full details refer to the relevant systemspecific manuals. To avoid an overlap of error numbers between the common error numbers and the database specific error numbers. C-ISAM Error Numbers Error Description 100 Duplicate record 101 File not open 102 Bad argument 103 Bad key description 104 Too many files open 105 File corrupt 106 Not exclusive open 107 Record or file locked 108 Key exists 109 Primary key 110 End/Beginning of file 111 Record not found 112 No current record 113 File locked 219 .For example: . To enable applications to trap specific common errors. Note: The list of error numbers provided is not exhaustive.  C-ISAM Error Numbers  Error Macros  Oracle Error Numbers  IDS Error Numbers  PRONTO-RAD 4GL Error Numbers  SQL Server Error Numbers  UNIX/Linux Error Numbers. the macro details will specify the likely cause and suggest a remedy. or even increasing available disk size. Where it is anticipated that a 4GL Application Developer may be able to discover and rectify the problem causing the error. Macro Equivalent Error Number and Description ENOENT 2 No such file or directory Cause/ Remedy EACCESS 13 Ensure path and file is valid. The solutions to many of these problems will be such things as running Database or Operating System-Specific Utilities. These errors mainly refer to internal PRONTO-Xi calls to the Database Engine or Operating System. increasing the values of system parameters. Permission denied Cause/ Remedy Check system permissions on file. EMFILE 24 Too many open files ENOSPC 28 No space left on device ENOLCK 46 No lock EDUPL 100 Duplicate record Cause/ Program has not endeavoured to check if record 220 . there is very little a 4GL Application Developer can do. Errors such as ‘Bad Argument’ or ‘Cannot allocate memory’ will need to be referred to PRONTO-Xi Systems Technical Staff or Database Administrators to check.114 File name too long 115 Cannot create lock file 116 Cannot allocate memory 117 Bad custom collating 118 Cannot read log file record 119 Bad transaction log file record 120 Cannot open transaction log file 121 Write error on transaction log 122 Not in transaction 123 No shared memory 124 Beginning of transaction not found 125 Cannot use network file server 126 Bad record number 127 No primary key 128 No logging 129 Too many users 130 Dbspace not found 131 No free disk space 132 Record too long 133 Audit trail exists 134 No more locks Error Macros Under most of the following error conditions. To access this facility enter the following at the command line: oerr facility error Then type the error number.Remedy exists having current key fields values prior to insert/update operation. EFLOCKED 113 File locked Cause/ Remedy EFNAME 114 Open OBJECT lock (exclusive lock) failed as some other process already had the object locked. Must be handled by the 4GL Application Developer. When using Get OBJECT CURRENT to regain currency when did not previously have a record CURRENT. For example: oerr ora 7300 Based on this example: 221 . ETOOMANY 104 Too many files open EBADFILE 105 Bad File Descriptor ENOTEXCL 106 Not exclusive open ELOCKED 107 Record or file locked (*) Cause/ Remedy Get OBJECT lock failed as some other process already had the record locked. 5. EKEXISTS 108 Key exists EPRIMKEY 109 Primary key EENDFILE 110 End/Beginning of file Cause/ Remedy ENOREC 111 Record not found Cause/ Remedy ENOCURR 112 Error will occur when attempting GET NEXT at end of file OR GET PREVIOUS at beginning of file. ENOSHMEM 123 No shared memory ERECORDCHANGED 10011 Record change prior to update using optimistic lock Oracle Error Numbers The oerr facility should be used when the error number is an Oracle error. File name too long or too short Cause/ Remedy Path and File name exceeds operating system specific maximums or is ZERO length (BLANK). No Current record Cause/ Remedy 4. ENOTOPEN 101 File not open EBADARG 102 Bad argument (usually a corrupted C-ISAM file) EBADKEY 103 Bad key description Cause/ Remedy Physical File exists with one data definition and subsequent re-open of file uses different data definition (notably the key fields). Attempting to update or delete record that is not locked. IDS Error Numbers The following IDS command can be used to look up an error number: $INFORMIXDIR/bin/finderr <error-number> These commands are for a UNIX operating system only. 7300 Is the error. UNIX/Linux Error Numbers Error Description 1 Not owner 2 No such file or directory 3 No such process 222 . access the IBM Informix Dynamic Server website and search for ‘error codes’ or a specific error code / number. These commands are for a UNIX operating system only. PRONTO-RAD 4GL Error Numbers Error Description 10000 Change of index during sequential read 10001 Change of direction during sequential read 10002 Current record changed 10003 Update/Delete on record that was not locked 10004 At beginning of list 10005 File has transactions active 10006 Transaction in progress 10007 Field not in original select list 10008 PROSERVER not of correct level or not available 10009 Too many servers (obsolete) 10010 Network access is not allowed 10011 Record changed prior to update using optimistic lock 10012 Failed data trigger validation SQL Server Error Numbers SQL Server error numbers can be found by running either of the following 4GL programs:  “rdbms_adm”  “sqlserver_adm” The Error Numbers option will show details of the SQL Server errors. Tip: Alternatively.ora Is the facility. 4 Interrupted system call 5 I/O error 6 No such device or address 7 Arg list too long 8 Exec format error 9 Bad file number 10 No child process 11 Resource temporarily unavailable 12 Not enough space 13 Permission denied 14 Bad address 15 Block device required 16 Device or resource busy 17 File exists 18 Cross-device link 19 No such device 20 Not a directory 21 Is a directory 22 Invalid argument 23 File table overflow 24 Too many open files 25 Not a character device (or) Not a typewriter 26 Text file busy 27 File too large 28 No space left on device 29 Illegal seek 30 Read-only file system 31 Too many links 32 Broken pipe 33 Math argument 34 Result too large 35 No message of desired type 36 Identifier removed 37 Reserved Numbers from 37 to 44 45 Deadlock 46 No lock 60 Not a stream 62 Stream ioctl timeout 63 No stream resources 64 Machine is not on the network 223 . must specify the new row. The old and new row values are the same for insert and delete triggers. Changes to the data made using the PROCOPY utility.5v3. will not invoke PRONTO-Xi data triggers. Returning values are ignored for all other trigger types and all userdefined triggers regardless of their type. TRIGGER-TYPE PIC 9(4) RETURNING newrow. Note: Data triggers are only invoked for operations tables generated by a release 6. Any changes made to values of the new row by a before update or before insert trigger will be returned to the calling routine and applied to the operation.out corrupted 86 Attempting to link in more shared libraries than system limit 87 Cannot exec a shared library directly Data Triggers Data triggers are defined in the data dictionaries. Standard triggers for an object are defined in the same dictionary in which the object is defined.*. For example: PROCEDURE deb-master-trigger EXPORT PARAMETERS ARE oldrow. newrow. These triggers will be compiled into any program that references that object. A trigger routine has three parameters passed to it. the second is new row and the third is the trigger type. 224 . Data triggers must be defined in component libraries. For full details on how to maintain data triggers refer to the Dictionary Maintenance manual.* A standard (compiled in) trigger may define a RETURNING clause specifying the new row. For full details on component libraries refer to the PRONTO-Xi Software Development Kit documentation.65 No package 66 Resource is remote 67 Virtual circuit is gone 68 Advertise error 69 Srmount error 70 Communication error 71 Protocol error 74 Multihop attempted 77 Bad message 83 Cannot access a needed shared library 84 Accessing a corrupted shared library 85 lib section in a. if used. Data triggers are only invoked for changes to the data made by 4GL programs (including browse screens). Triggers are not invoked as a result of the SERIAL statement. external (non-PRONTO) applications.*. The first is the old row. or changes made directly to the database.* LIKE deb-master.* LIKE deb-master. The returning clause is optional and. PRONTO-SQL.0 (or later) compiler.