Informix 4GL Standards

The following topics are discussed in this document:

• General Standards
• Program Appearance
• Database Interface Standards
• INFORMIX-PERFORM Files (Screens)
• Screen Records
• List Windows
• Naming Conventions

General Standards Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Contents of Section Source Fileheader Variables and Functions WHENEVER ERROR DEFER Error Handling GOTO Common Library Routines Hard Coding Names Comments Source Fileheader Include the following source fileheader description at the beginning of every source file: ################################################### # Module: # Description: # # Functions: # # $Source$ # $Revision$ # $Author$ # $Date$ # $Log$ ################################################### The header contains a description of the module and the functions contained in the module. These features enhance readability and maintainability. This header is in usr/aa/pr/bin/prog_hdr.4gl; read it into the beginning of each file and then update it. Add the following information to each module. This information is necessary for the Workbench Version Control System (VCS): DEFINE rcs_header CHAR(100) LET rcs_header = "$Header$" Include the following function header at the beginning of every function: ################################################### # Function: # Description: > # # # Incoming Parameters: # Outgoing Parameters: # Returns: # # Revision History # Date Changed By Description # --------------------------------------- ################################################### The header should contain the function name, a description of the function, and any incoming and outgoing parameters. When you make changes to the function, include your ID, the date the changes take effect, and a brief description of the modifications that were made. This header is in /usr/aa/pr/bin/func_hdr.4gl. Variables and Functions If you group common functions for a subsystem in a single module, and functions within that module use the same variables, you can make those variables modular in scope. Otherwise, use global or local variables. Code all global variables in one file (one global file/object) to reduce duplicate variables, enforce standards, and improve maintainability. The function init_globs() initializes all global variables. Use descriptive variable and function names. To improve readability, separate words and abbreviations in variable and function names with an underscore (_). Do not use an asterisk (*) when defining variables or when performing a database action. For example, you could not refer to all columns in the table str by coding str.*. However, you may use an asterisk as a wildcard when referring to defined variables; for instance you could code gr_str.*. This requirement helps to ensure that programs run properly across all stages of the life cycle and that code promotions are not required when database changes are promoted. To improve maintainability, do not use recursive functions. Another way to improve maintainability is to code each function to have only one entry point and one exit point. {Note: The RETURN statement is an exception.} Related information:"Comments", "Text Case". "Naming_Conventions" WHENEVER ERROR Include the WHENEVER ERROR CONTINUE statement at the top of each source module. Use the WHENEVER ERROR STOP statement for debugging; be sure to remove the statement from each source module and replace it with WHENEVER ERROR CONTINUE. DEFER Include the DEFER INTERRUPT and DEFER QUIT statements at the start of each MAIN function. These statements have provisions to handle unexpected conditions; their use increases reliability of the code. These statements can be commented out during development and debugging. Remember to remove the comments from the last exec. Error Handling Use a RETURN statement only when there is the possibility of needing to return an error code - after an error is detected or at the end of a function. Code is easier to read and maintain if you RETURN immediately after an error. A common architecture routine handles error functions. Error message text is stored in the INFORMIX msg table; the text is accessed by passing the message number to the Architecture Message Manager (aap030.4gl). This ensures that the same error handling is being used throughout the STORES system. The exec_log_proc and exec_abend_mgr handle all logging of errors. The msg_mgr displays all messages. Refer to the UNIX Online Architecture documentation for an explanation of how each function is called. GOTO The following statements are implied GOTOs. Use them with caution so you do not create more than one exit point from a function or loop: WHILE constant EXIT WHILE CONTINUE WHILE CONTINUE FOR CONTINUE FOREACH EXIT CASE Do not use the INFORMIX-4GL GOTO construct. Common Library Routines All common library routines - for example, calculations - must be handled by the Architecture. This ensures that only one function is written for each common library routine. The Architecture team maintains a list of common services. Examples include the Abend Manager (exec_abend_proc) and the Checkpoint Manager (ckpt_mgr.) Hard Coding Names Do not hard-code path names or file names in 4GL programs. Alternatives include passing them to the programs as arguments on the command line setting up environment variables for them storing them in a database. Comments Start all commented lines with a pound sign -- #. Comments improve maintainability of the code. Comments that begin with the pound sign are easier to find in the code. Document all variables with comments that give a description of what the variables represent. Do not use any other Informix comment symbols, including "curly braces" { } and hyphens (--). Use of these symbols can be misleading.

Program Appearance Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Contents of Section Writing Readable Code Indenting Code Text Case Conditional Statements Defining PREPARE Statements Defining Cursors CASE Statements Writing Readable Code Use the following guidelines to write programs that are easy to read, easy to maintain, and easy to debug. Code a space character after a comma to improve readability. Example: SELECT fname, lname, address_ln1 FROM customer Nonexample: SELECT fname,lname,address_ln1 FROM customer Code a space before and after each set of parentheses. Example: IF ( condition ) THEN statement ELSE other statement END IF Nonexample: IF(condition)THEN statement ELSE other statement END IF Indenting Code Use the space bar to indent each level of code four spaces to the right of the preceding level. Do not use Tab to indent lines of code; some printers do not recognize Tabs. Use the UNIX EXPAND command to remove tabs. Text Case Code all INFORMIX keywords and commands in UPPERCASE. The command ic in usr/aa/pr/bin converts from lower to uppercase all INFORMIX key words and commands. Example:cat wrap.4gl | ic > some file. Code variables and function names in lowercase. Conditional Statements Use paired parentheses "( )" in all conditional statements. Example: WHILE ( NOT int_flag AND cnt <=4 ) statement END WHILE Defining PREPARE Statements Define PREPARE statements by preceding them with st_. Example: PREPARE st_sel_ord FROM g_sql_ord This improves maintainability and readability. Always use PREPARE statements when an SQL statement will be executed multiple times. Use a meaningful name after the underscore. Defining Cursors When defining CURSORs, precede them with a c_ to improve maintainability and readability. Example: DECLARE c_sel_ord CURSOR FOR SELECT ord1, ord2 FROM orders CASE Statements Use the following format to code variables in CASE statements: Example: WHEN variable = 0 statement END CASE This format improves readability and maintainability, especially if the variables continue to more than one page. Nonexample: CASE variable WHEN 0 statement END CASE

Database Interface Standards Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Contents of Section Only the most important programming-related database standards are listed in this section. See the Informix SQL standards for a complete listing of database interface standards. Referential Integrity Checking Values of SQLCA.xxx Qualified Column Names Database Transactions ROWID Month Arithmetic Aggregate Functions LOCK TABLE Referential Integrity Place all parent and child updates within one transaction to ensure referential integrity. Always verify that referential integrity is being maintained. Check error codes after each COMMIT WORK to ensure that each transaction has successfully completed. This ensures that no child tables are inserted without having parent tables, and that the values of fields are acceptable. INFORMIX supports referential integrity. The preferred method is SELECT COUNT (*) against the parent table where the principal key equals the value of the foreign key assigned. This involves verifying that the value of each foreign key exists as a value of a primary key in the parent table. Checking Values of SQLCA.xxx Always verify that SQLCA.SQLCODE (status) equals zero after executing a database statement that modifies the database. If possible, check the values of SQLCA.SQLERRD[3] after each UPDATE or DELETE statement. SQLCA.SQLERRD[3] contains the number of rows updated or deleted. Remember that an UPDATE or DELETE can impact zero rows and still be considered successful in INFORMIX. Qualified Column Names Qualify column names within each SQL statement with the name of the table in which the column occurs. Example: SELECT orders.line_item, customer.name FROM order, customer For consistency, this standard applies to even single-table SQL statements. Database Transactions For a transaction, code the BEGIN WORK, COMMIT WORK, and ROLLBACK WORK statements within one function. The Architecture error routine exec_abend_proc issues ROLLBACKs. If you do not call exec_abend_proc, your work is not be rolled back in the event of an error. In this case only, you must include the ROLLBACK WORK command. Keep all database transactions (BEGIN WORK .... COMMIT WORK) as short as possible. In particular, do not wait for user input within a database transaction. INFORMIX holds locks on any data that is impacted by the transaction. Keeping transactions short improves concurrent access to the database. ROWID Do not use the INFORMIX reserved word ROWID. Month Arithmetic Be careful using "month" arithmetic: "month" does not represent a consistent unit of measure. Example:(3/31/94 - 6 months) + 6 months does not equal 3/31/94. Aggregate Functions INFORMIX aggregate functions - for example, SUM and MIN - ignore NULL values. Example: SUM(column_a) is the sum of all rows with non-NULL column_a values. It will be NULL only if all values for column_a are NULL. LOCK TABLE Consult with the INFORMIX DBAs before using the LOCK TABLE command.

Informix Perform Files Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Contents of Section Apply the following standards when coding applications for any character-based INFORMIX system. Programmers coding for character-based INFORMIX systems should take advantage of the features of INFORMIX-PERFORM capabilities whenever possible. Unfortunately, some requirements of the application will not allow use of some of the features of INFORMIX-PERFORM screens. Include the following standard file header as minimum documentation in all INFORMIX-PERFORM files. {******************************************************* * Module: * Description * * Functions: * * * $Source$ * $Revision$ * $Author$ * $Date * $Log$ * ********************************************************} This header is in /usr/aa/pr/bin/per_hdr.per which can be read in and updated for each screen. Use a COMMENTS command with a NOENTRY field to include the version control "$Header$" information. Example: dlog_id = formonly.dsp_dlog_id, NOENTRY, COMMENTS = "$Header$'; List only tables that are referenced in the ATTRIBUTES section in the TABLES section of the file. In many cases the TABLES section can be omitted because the file contains FORMONLY statements for every field in the form. The preferred approach is to use the FORMONLY object with the DATABASE statement. No tables are listed in the TABLES section. All screen fields are preceded with FORMONLY in the ATTRIBUTES section. Note: TIGER generates forms with DATABASE FORMONLY. The following standards apply to the ATTRIBUTES section of the file: Do not use the INCLUDE or COMMENTS attribute during input; standard comments and INCLUDE are not adequate. Use AFTER FIELD in combination with the msg manager All field tag names should be unique in the form. This permits using the BY NAME command in DISPLAY and INPUT statements. Do not use the AUTONEXT attribute. The UPSHIFT attribute may be used only for fields on which you do not expect to require matching.

Screen Records Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Place input from a PERFORM screen into a 4GL record variable that has a one-to-one correspondence with a screen record defined in the PERFORM file. Structuring records this way permits use of the INPUT gr_[record].* and BY NAME syntaxes, which are shorter and easier to read. Programmers should make use of the screen records feature in PERFORM. The screen record (for an array) name should be sa_<meaningful name>. If the order of fields in the screen record reflects the order in which input is taken in the 4GL program the 4GL INPUT statements are easier to read.

List Windows Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Reference the "Online Window" section of the UNIX Online Standards for standards that apply to using windows in applications. Related Information: Naming Conventions

Naming Conventions Go to Top of this page General Standards Program Appearance Database Interface Standards INFORMIX-PERFORM Files (Screens) Screen Records List Windows Naming Conventions

Contents of Section Use the following naming conventions for naming database objects, functions, programs, forms, windows, program variables, screen variables and other objects in the Home Depot Stores system. Unless specified otherwise, use the abbreviations found in the lists of standard abbreviations and standard class words available in the Brownstone Data Dictionary or from the Data Management team. Directories Functions Module Files Global Files Program Files Rapid System Development (RDS) Files Forms FormsXpress Windows Global Variables Module Variables Local Variables Screen Variables Other Software Objects Directories Directories correspond to life cycle phases (LCPs) for software development. Abbreviations for these directories include Directory Life Cycle ad Application Development pr Production (Development System only) de Deployment Several directories exist below the LCP directories. Each of these lower-level directories contain files according to the following system: Directory Contents bin Executable files such as *.4ge's, C programs, and UNIX scripts lib Compiled library functions src All source code for the system dbs Data files; for example, files may contain database "unload" data or ASCII data used for table updates Use the underscore character ( _ ) to separate all abbreviations within names. Functions Use meaningful prefixes to reflect the primary purpose of a function. The following table provides suggestions for creating functions. Use functions names that are meaningful; use standard abbreviations whenever possible. Suggested Prefix Purpose cmp Performs computations db Performs one or more basic database operation del Deletes information from the database dsp Displays information to the user err Performs error handling ins Inserts or adds information to the database inp Receives input from the user sel Receives or selects information from the database upd Updates database information val Validates information Module Files The syntax for the names of module files is xxp###m##.4gl The following table explains the parts of the name syntax: Part Meaning xx Two-character subsystem code p A constant indicating a program ### Program's sequential number dsp Displays information to the user m A constant indicating a module ## Module's sequential number End all module filenames (INFORMIX-4GL source code files) with the suffix .4gl. Module file names, excluding the ".4gl" suffix, should not exceed 18 characters. Global Files The syntax for the names of global files is xxp###_gbl.4gl The following table explains the parts of the name syntax: Part Meaning xx Two-character subsystem code p A constant indicating a program ### Program's sequential number gbl A constant indicating a global file End all module filenames (INFORMIX-4GL source code files) with the suffix .4gl. Program Files The syntax for the names of module files is xxp###.4ge. The following table explains the parts of the name syntax: Part Meaning xx Two-character subsystem code p A constant indicating a program ### Program's sequential number 4ge A constant indicating a program file Program file names, excluding the suffix, should not exceed eight characters. Rapid System Development Rapid System Development (RDS) program file names end with the suffix .4gi. Forms Definition: A form is any screen that occupies the entire display area of a terminal device. Descriptions and layouts of forms are found in .per files. The syntax for the names of form files is xxs###xAAA.per. The following table explains the parts of the name syntax: Part Meaning xx Two-character subsystem code s A constant indicating a form ### Program's sequential number x Sequential characters: a, b, c, ..., z AAA Language code; for example, ENG (English) per A constant indicating a form file The name of a form in an INFORMIX-4GL program should be identical to the file name of the .per file where the form is described. Form names, excluding the ".per" suffix, should not exceed 18 characters. FormsXpress Files The syntax for the names of FormsXpress files is xxrnnnzNLS.fgl The following table explains the parts of the name syntax: Part Meaning xx Two-character subsystem code p FormsXpress overlay d m a Document file Map data Format file (used with NLS extension) nnn Program number z An alphabetic character NLS Language in which the report is written fgl The file extension for a FormsXpress source object is fgl. The file extension for a FormsXpress ship object is xgl Windows Definition: A window is a portion of any screen displayed over an existing form or on top of other windows. Find descriptions and layouts for windows in .per files The reference name of a window in an INFORMIX-4GL program should be the same as the file name of the .per file where the window is described. Most windows will be handled by the Architecture and the names will be populated by TIGER (Template Interactive Generation Environment). Global Variables The following table explains the parts of the name syntax for global variables: Prefix Meaning g_[variable name] Global program variable name defined in a globals .4gl file ga_* Global program array name defined in a globals .4gl file gr_*.* Global program record name defined in a globals .4gl file Note:Arrays of records use the form gr_*.*[array boundary]. Module Variables The following table explains the parts of the name syntax for module variables: Prefix Meaning m_* Modular program variable name defined in a globals .4gl file ma_* Module array name defined in a globals .4gl file mr_*.* Module record name defined in a globals .4gl file Note:Arrays of records use the form gr_*.*[array boundary]. Local Variables The following table explains the parts of the name syntax for local variables: Prefix Meaning p_* Local program variable name defined in a function pa_* Local program array name defined in a function pr_*.* Local module program variable name defined in a function Screen Variables The following table explains the parts of the name syntax for local variables: Prefix Meaning sa_* Screen array name defined in a .per file sr_*.* Screen record name defined in a .per file Other Software Objects The following table explains the parts of the name syntax for other software objects: Prefix Meaning c_* Informix-4GL cursor names st_*.* Statement name used in Informix-4GL PREPARE and EXECUTE statements w_* A window

Return to top of this page. This is the end of the INFORMIX SQL Standards.
Last updated: 2/27/97 4:05 PM
Webmaster: Lallie Heard, Ext. 17536 © Copyright 1997 The Home Depot Inc.