Developers Manual

Developers Manual
NOTICE
Civica reserves the right to make changes without notice in the specifications and materials contained herein and shall not be responsible for any damages (including consequential) caused by reliance on the materials presented including but not limited to typographic or arithmetic errors, company policy and pricing information. Civica makes no warranty of any kind with regard to this material, including, but not limited to, implied warranties of merchantability and fitness for a particular purpose. This document contains proprietary information that is protected by copyright. All rights are reserved. No part of this document may be photocopied or reproduced without prior consent of Civica. AUTHORITY is a trademark of the Civica Pty Limited. Company names, company logos, and products mentioned herein are trademarks or registered trademarks of their respective trademark holders. 2011 Civica Pty Limited. All Rights Reserved.
Revision History Date Version No. Author Description
Contents
DEVELOPMENT ENVIRONMENT .......................................................................... 1 OVERVIEW ..................................................................................................................... 1 DIRECTORY STRUCTURE .................................................................................................... 3
AUTHORITY Directory Structure ......................................................................................................... 4 PROCEDURES .................................................................................................................. 6 (After editing a source file).............................................................................................................. 7 Creating a Project Tree.................................................................................................................... 7 Creating a New Program/ Directory within the Product directory.................................................. 8 Screen Layout .................................................................................................................................. 9 Adding a new directory to a previous branch ................................................................................. 9 Adding a new source file ............................................................................................................... 10 Editing a source file ....................................................................................................................... 10 Checking For Linked Files............................................................................................................... 11 Making changes in a branch (previous release) ............................................................................ 12 Adding a new program to a previous branch ................................................................................ 13 Getting the latest version of a program ........................................................................................ 14 Removing a Source File ................................................................................................................. 15 Removing an entire program ........................................................................................................ 16 Checking in a new binary file (eg crystal report) ........................................................................... 19 Recording Tables used in a Crystal Report .................................................................................... 19 Unlocking a specific file revision ................................................................................................... 20 Compiling a program with an old file revision .............................................................................. 20 Restoring an old revision permanently ......................................................................................... 20 TESTPATCH .................................................................................................................. 21 Error Messages ............................................................................................................................. 22
DATABASE ENVIRONMENTS ............................................................................. 23 OVERVIEW ................................................................................................................... 23 FILES LOCATION ............................................................................................................ 23 WHERE DO I PUT MY SQL ............................................................................................... 24 PROCEDURES ................................................................................................................ 25 TOOLS ............................................................................................................. 36 AUTHORITY SCRIPTS....................................................................................................... 36
Program Listing ............................................................................................................................. 36 Program Name .............................................................................................................................. 36 Report Listing ................................................................................................................................ 36 Schema Listing .............................................................................................................................. 37 RUNNING A PROGRAM ............................................................................................... 38 OUTPUT DEBUG FILES .............................................................................................. 38 DEBUGGER ................................................................................................................ 38 GREP ......................................................................................................................... 40 HIDING OR INACTIVATING FIELDS, SECTIONS ........................................................... 40 WHEREIS ................................................................................................................... 41 SQL EXPLAIN ............................................................................................................... 42
WACGEN ......................................................................................................... 44
Authority Developers Manual
Civica Pty Limited
4JS ............................................................................................................................ 44 TECH WIKI ....................................................................................................... 44 APPENDIX 1: DATABASE COLUMN ABBREVIATIONS ........................................... 45
Developers Manual
Commercial in Confidence
Page 4 of 54
Civica Pty Limited
Version Control
Date 4/2/04 20/3/04 6/9/04 08/08/2008 Version Number 1.1 1.2 1.3 1.4 Author Ann Landers Roselynne Stuart Chris Sobb Ann Landers Description Updated for changes in crystal reports Add in instructions for Summary info for Crystal reports. Added Modules by Knowledge Centre Appendix Removed audit instructions as they are now in the generator. Added georgeq website for report lister. Updated QA procedure document. Updated out of date areas Added section on hiding/inactivating fields.
10/08/2009 7/12/2009
1.5 1.6
Robert Davies Robert Davies
DEVELOPMENT ENVIRONMENT
Overview
The principle goals for a common development environment for Civica Local Government products should be to maximize productivity by making interactions between developers work as simply as possible. Civica source code resides in one place on the network, in a source tree containing files under a code control scheme, RCS. The major issues covered by RCS are multiple concurrent edits, archiving of changes, version control and the maintenance of a change history. No files should reside in the source tree unless they are under RCS. Files should not be added to the source code tree unless attempts are made to ensure that similar code does not already reside in the tree and that the new code is as generally useful as possible. This generally involves some communication. Documentation should also reside in the source tree. From this source code tree the files are checked out (read-only) into a master development area. When this is done, the code can be distributed to all machines on the network and the system built. This is usually on overnight process to spare users from the intensive CPU overhead. This sets the system to a known state on all machines and isolates architecture specific vagaries. The /sand/src file system exists on one machine, and is made available on other development systems via NFS. Each development platform has a local /sand/devel. Each developer creates one or more project areas (consisting of directory trees) on the same file system as the master tree. This allows files in the project tree to be hard-linked from the master development tree. As code in the project is changed, either by checking out source files for edit or creating new files, the hard links are broken and the affected files are kept local to the project tree. In this way disc space
Developers Manual
Page 1 of 54
Civica Pty Limited
requirements are kept to a minimum, but one developers experimental changes do not adversely affect others in the team. Each week the entire master tree is deleted, making it important that no code is edited or created in the master tree. The entire source tree is then checked out and everything is built. This breaks the hard links between master tree files and their equivalents in project areas, though files within project areas will remain linked to each other, keeping their version of files as at the start of the project. There is always the possibility that the entire system will not build without user intervention, but users will still have their hard-linked versions to continue working on. When the build is completed, developers are advised to re-link to the master tree to free disc space. The regular building process guarantees steady progress from one build to another build ensuring that developments in various pieces of code work together at regular intervals. At the same time it allows developers to capture a snapshot of the system in a known state and not have it change until they choose. The danger is that users will not regularly keep their project tree up-to-date with the current master tree. There are commands that can be used to reclaim disk space and/or bring a project tree up to date with respect to checked-in source and utilities, these are explained in a later chapter. It is important that references to other files and directories (such as in scripts) be relative, not absolute, so that a project tree can be self-contained. This is important because: when the master tree is undergoing its regular rebuild, it is deleted and may not be fully recreated for up to a day or so; changes to common utilities, libraries, etc. should be made and tested within a project tree without affecting other developers; and when off-site development is required, it should not be necessary to take large parts of the master tree.
It is important that users should always work in their own account. This ensures that changes and new files are marked with their real owner. Project areas are intended to be a place where multiple users can work together, avoiding the temptation for users to log in to a shared account and create files for which no one will admit responsibility. Directory structures within the development tree are exactly as they appear in the source tree. At the first level these are composed of logical code areas, chiefly products and cross-product libraries.
Developers Manual
Page 2 of 54
Civica Pty Limited
Directory Structure
The directory tree /sand typically has the following sub-directories available on each development system: src contains checked in source in RCS files. devel in turn contains the following types of subdirectories: master - Consists of all code from the src tree, checked out and compiled automatically once per week or as required. branches (releases) - Based on the source at the time of a release for an issued product; bug fixes may be applied here to created software patches for issue to customers. user projects - Project areas in which (usually) individuals undertake development; most files are in fact hard links to files in the master tree. Within each of these areas the logical structure of the products, as outlined below, is replicated.
Developers Manual
Page 3 of 54
Civica Pty Limited
AUTHORITY Directory Structure The AUTHORITY product resides in directory, typically referred to as $APPL. Under this are sub directories for each module with an extension of .4gm. These in turn contain one directory for each program with an extension of .4gs. The 4gs directories contain all the source and objects for the program. Top level of the tree. $APPL
.4gm
Module level.
.4gs
Program group level.
.dsp (layout) .trg (code)
Program components.
In addition to the modules, there is some special purpose directories that are now described. Libraries Integration Area This directory has been placed in the $APPL structure to store any scripts, stored procedures, sqls or triggers etc used on site. The structure of this directory will be: $APPL/ integration/ third party name (eg finance_one) site (if site specific) scripts (if generic for all installations of this product) scripts (if not generic for all installations of this product) eg $APPL/integration/impala/newcastle/imp_prop1.sql.
Developers Manual
Page 4 of 54
Civica Pty Limited
A README file describing the files, how they are used (eg trigger, stored procedure etc) and their use will be in each directory to better allow support of these scripts. The naming format is as follows : Shell Scripts: *.sh SQLs, Triggers and Stored Procedures:
*.sql.
This area is not for one off scripts that have been created for fixes etc.
Developers Manual
Page 5 of 54
Civica Pty Limited
Procedures
Contents
DEVELOPMENT ENVIRONMENT ............................................................................. 1 OVERVIEW ..................................................................................................................... 1 DIRECTORY STRUCTURE .................................................................................................... 3
AUTHORITY Directory Structure ......................................................................................................... 4 PROCEDURES .................................................................................................................. 6 (After editing a source file).............................................................................................................. 7 Creating a Project Tree.................................................................................................................... 7 Creating a New Program/ Directory within the Product directory.................................................. 8 Screen Layout .................................................................................................................................. 9 Adding a new directory to a previous branch ................................................................................. 9 Adding a new source file ............................................................................................................... 10 Editing a source file ....................................................................................................................... 10 Checking For Linked Files............................................................................................................... 11 Making changes in a branch (previous release) ............................................................................ 12 Adding a new program to a previous branch ................................................................................ 13 Getting the latest version of a program ........................................................................................ 14 Removing a Source File ................................................................................................................. 15 Removing an entire program ........................................................................................................ 16 Checking in a new binary file (eg crystal report) ........................................................................... 19 Recording Tables used in a Crystal Report .................................................................................... 19 Unlocking a specific file revision ................................................................................................... 20 Compiling a program with an old file revision .............................................................................. 20 Restoring an old revision permanently ......................................................................................... 20 TESTPATCH .................................................................................................................. 21 Error Messages ............................................................................................................................. 22
DATABASE ENVIRONMENTS ................................................................................. 23 OVERVIEW ................................................................................................................... 23 FILES LOCATION ............................................................................................................ 23 WHERE DO I PUT MY SQL ............................................................................................... 24 PROCEDURES ................................................................................................................ 25
Creating a new table ......................................................................... Error! Bookmark not defined. Altering an existing table .................................................................. Error! Bookmark not defined. Creating or altering other objects ..................................................... Error! Bookmark not defined. Development Database Sync Procedures .......................................... Error! Bookmark not defined. Modifying the *.sql files .................................................................... Error! Bookmark not defined. The authver_<version>.pl scripts ...................................................... Error! Bookmark not defined.
DEVELOPMENT PROCESS...................................................................................... 36 TOOLS.................................................................................................................. 36 AUTHORITY SCRIPTS....................................................................................................... 36

Program Listing ............................................................................................................................. 36 Program Name .............................................................................................................................. 36 Report Listing ................................................................................................................................ 36 Schema Listing .............................................................................................................................. 37
Developers Manual
Page 6 of 54
Civica Pty Limited
Running a program ....................................................................................................................... 38 Output Debug Files........................................................................................................................ 38 Whereis ......................................................................................................................................... 41 SQL EXPLAIN ............................................................................................................... 42
WACGEN.............................................................................................................. 44 4JS ............................................................................................................................ 44 RCS COMMANDS .............................................................. ERROR! BOOKMARK NOT DEFINED. APPENDIX 1: DATABASE COLUMN ABBREVIATIONS ............................................. 45
(After editing a source file) Temporary tables can be useful in a program to gather and sort rows from other tables. When creating a temporary table in a program, adhere to the following: Name the temporary table tmp_name. Do not name the temporary table in the same standard as fixed tables ie with a suffix of au. Drop the temp table once the program has finished using it. Add the temporary table to the exitprog library that lives in $APPL/lib1.4gs. This library is required to clean up DBTEMP which contains the path to the dumping area for the temporary files.
Creating a Project Tree All development work needs to be done within a working area called a project. Generally each programmer has their own project to work in but they can have more then one if working on multiple development streams. In the following example, a development project called "elvisp" is created: $ cd /sand/devel $ mkdir elvisp $ cd master $ find auth/all.4gm auth/Application.ctl auth/.stage -print | cpio -pdlumv ../elvisp This will create a project suitable for work on the SandThing software. The user should then set the environment variable PROJECT and re-execute the commands in his/her .profile: $ PROJECT=elvisp; export PROJECT $ . ~/.profile
Developers Manual
Page 7 of 54
Civica Pty Limited
The new project replicates a subset of the directories that are under master. If creating a project that is to hang of a branch rather then the trunk then you will need to name the project userbranch, ie elvisp4_5_1 where elvisp is the user and 4_5_1 is the branch. This is what enables the check in process (rco) to know which branch you are checking into.
Creating a New Program/ Directory within the Product directory Allocate the Program Id by first changing to the appropriate directory within your project,eg # cd $project/module.4gm Go to the source directory # cd `src` List the contents of this directory and check that new program directory that you wish to create doesnt already exist. # ls Go back to your project # cd Create the new program directory within youre your project # mkdir program.4gs Move into the new directory # cd program.4gs Create the corresponding directory in the source tree # \mkdir `src` Create a symbolic link named RCS, pointing to the corresponding source directory, to be used by RCS commands. # ln -s `src` RCS Create source files using vi and compile Once you are finished or at an appropriate stage in the development life cycle all the source should be checked into source code control. # ci u filename | filename2 You will be prompted to enter a description for the program. A short description is all that is needed, perhaps the programs name.
Developers Manual
Page 8 of 54
Civica Pty Limited
If the program is for general distribution to customers as part of an Authority release then add an entry into the manifest file (MANIFEST_auth) in auth directory (ie $APPL). For programs a program directory listed in the manifest all the .42f , .42m and .42r files are automatically included. If other files are required for a program then these need to be explicitly specified. For example, to add an entry for e_pu001 add the two lines for e_pu001.4gs under the section for module pu.4gm. Making an effort to keep the entries sorted for ease of maintenance. If the program required a sql file to be release with it, e.g. e_pu001.sql, then the additional entry for e_pu001.sql would have to be added to the manifest. e.g.
SOURCEDIR: pu.4gm 2775 pu.4gm SOURCEDIR: pu.4gm/e_pu001.4gs 2775 pu.4gm/e_pu001.4gs 555 pu.4gm/e_pu001.4gs
e_pu001.sql
Check out and lock the manifest, update and check the manifest back in.
# rco l MANIFEST_auth # vi MANIFEST_auth # ci u MANIFEST_auth
Please refer to the Development Process section of this manual for a checklist of what other processes need to be completed when creating a new program.
Screen Layout When creating a new screen, or modifying an existing one the size of the screen should not exceed the current minimum supported resolution of 1024 x 768. Before checking in a screen check this by adjusting your resolution accordingly.
Adding a new directory to a previous branch Make a new 4gs directory in 4.6 and put in the link to src as for the master. # cd RCS # mkrevlist * Check the list includes only files you wish to branch. If not list files instead of *. # mkrevlist * | rcsmark -f -b "Authority 6.0" -n auth_6_0 -m /dev/null
Developers Manual
Page 9 of 54
Civica Pty Limited
Adding a new source file In your project create the new source file using vi. Compile and test the program. Once you are finished or at an appropriate stage in the development life cycle check the source file in using: # ci u filename When creating a new source file a RCS version control line (or what string) needs to be inserted. This enables you to type what filename and have it return the RCS version of the file. The line looks something like this: # @(#) $Id$ Civica The rcsid_insert script can be run on a checked out file to insert to appropriate string or if the file is checked in the -r option can be used so the script will check out and lock the file, add the string and check the file back in. rcsid_insert blah.src rcsid_insert -r blah.src # already checked out file # lock, add string, unlock
Where blah is the name of the file eg custom.src If youve created an extension it must be listed in a base.set file so the 4gl program knows to look for it.
Editing a source file In your project check out and lock the source file
# rco -l filename
NB You should only edit files with the following extensions, editing anything else will result in your changes being lost at the next make or generation of the screen. Never edit any .4gl files. src ext trg dsp base.set If a double lock occurs accidentily (one in 6.1 and one in 5.0 for example), you can unlock one of the revisions by doing the following:
# rcs -u<Revision Number> <filename>
To checkout a files revision number to compile the program using the old revision for whatever reason:
Developers Manual Commercial in Confidence Page 10 of 54
Civica Pty Limited
# rco -r<Revision Number> <filename>
Just rco <filename> to take it back to latest revision.
To revert a file to a previous revision permanently:

# rco -l <filename> # rco -r<Revision Number> <filename> # ci -u <filename>
And overwrite writable version.
Edit the source file using vi. Compile and test the program. Once you are finished or at an appropriate stage in the development life cycle check the source file in using :
# ci u filename
If you forgot to check out a source file with a lock and have accidentally edited it, do the following:
# rcsdiff filename
If only the changes you have made appear in the list of differences then:
# rcs l filename
otherwise:
# mv filename filename.bak # rco l filename # vi filename # merge your changes
or: create a file with context differences with rcsdiff c, edit the file to get your changes and use the patch command to merge your changes into the checked out and locked source file.
Checking For Linked Files The findulink command will list unlinked and writable files in your project
# cd $myproject # findulink
Developers Manual
Page 11 of 54
Civica Pty Limited
This will list all files such as printfile, etc which can be a lengthy list. An option to shorten this list is:
findulink | grep -v -e 'printfile' -e 'ann' -e '\.sql' -e '\.unl'
In this example, the findulink will exclude printfiles, sql, unload files and files named ann.
Making changes in a branch (previous release) When the change just needs to be made in the branch (previous release) then go to the branch or your project based on the branch
# cd $auth60
Check out the source file you need to change

# rco filename
Edit the source file using vi. Compile and test the program. Once you are finished or at an appropriate stage in the development life cycle check the source file in using :
# ci u filename
If making a change to the trunk (current release) and the branch (previous release) then there are two possibilities. Either make your change in the trunk and then the branch manually or make your change in the trunk and move the changes back to the branch using the btci (branch / trunk check in) command as described below. This attempts to retro fit the changes back. Which method you used would depend on how big the changes were and if any code changes have been made because of table changes in the trunk. To make changes in the branch follow the previous instructions. To use btci, a command to automatically retro fit changes to a branch do the following: Edit the file in your current release project. Ensure that you use rco to check out the program (refer Editing a source file earlier). To check the program back in use the following command rather then ci so that the changes will be retro fitted to branch (previous release).
# btci -u -r branch
Developers Manual
Page 12 of 54
Civica Pty Limited
You then go into vi so you can add a description of the change. If you have a lot of files to check in with the same log message you can save the message in a file and use the -c option.
# btci -u -r auth_6_0 -c <file_with_msg> <source_file>
This command will check the changes back into the trunk (current release) and attempt to retro fit the changes back to the previous release specified by the branch (ie auth_6_0). You will then need to go to the branch
# cd branch
Check out a copy of the new file. There is no need to lock the file unless you make additional changes to it to suit the branch.
# rco filename
Compile and test it to ensure that it works in the branch. If btci fails youre left with .logmsg and .diffs files as well as a branch directory containing the conflicts. You now have to merge these changes manually. Check the branch directory for the .rej files. The .rej files will list the changes that could not be successfully merged. After resolving the merge conflicts, check in the files from the sub-directory. Then change directory up on level and remove the diffs, logmsgs and branch folder. Remove the the .logmsg and .diffs files
# rm *logmsg # rm *diffs
And remove the branch direcory

# rm rf branch_X_X
Be very careful doing this, DO NOT use wildcards when deleting this directory.
For a further description of btci options type the following command:

# btci -h
Adding a new program to a previous branch
Developers Manual
Page 13 of 54
Civica Pty Limited
The example below shows how to create a new program i_rt145 in the 6.0 branch. The program has been created in the master tree of the current release. Substitute your program number and the appropriate release branch.
cd /sand/src/auth/rt.4gm/i_rt145.4gs cd RCS mkrevlist | rcsmark -b "Authority 6.0" -n auth_6_0 -f -m /dev/null mkrevlist builds a list of the file in the directory along with the revision number of the branch point in each file. rcsmark will create the branch in the file at the appropriate revision and add the symbolic name for the branch, being auth_6_0 This can also be used on single files. If filename.src is a new file and required in a previous release then: 1. Make sure the file is checked into master first. 2. cd RCS 3. mkrevlist filename.src,v | rcsmark f b Authority 4.6 n auth_6_0 m /dev/null 4. This file is now ready to be checked out in release 6.0. Getting the latest version of a program If someone else has changed a program and checked it back in and you wish to test this in your own project the quickest way to get the latest copy of this program is to use the following: authbld <prog name> [<prog name> ...] For each of the prog name specified, this script will check out the latest files required (using rco) and wac.make it. It will create the directories and the RCS links if necessary NB that the script will check out and build in the $APPL area, so make sure that's properly set before calling the script.
Developers Manual
Page 14 of 54
Civica Pty Limited
Removing a Source File It will sometimes be necessary to remove a source file from a program. This process involves moving the source files corresponding RCS (,v) file to a DELETED directory. The reason we move the file to a DELETED directory is to preserve the programs history. The removed file could still be required to build an old version of the software. The general procedure is illustrated in the following example using the program i_py001 and the source file ringmenu.src: 1. Change directory to your program directory
# cd i_py001.4gs # cd `src`
2. Check that the file is not locked. Someone might be working on it and subsequently check it in, undoing your efforts to remove the file.
# rlock ringmenu.src,v
3. Create a deleted directory in RCS

# mkdir DELETED
4. Move the unwanted rcs ',v' program files to the DELETED directory
# mv ringmenu.src,v DELETED
5. Change the owner

# rcs l ringmenu.src,v # rcs u ringmenu.src,v
6. Remove any unwanted symbolic names from the RCS ',v' file. If the file is still required for prior releases then this step can be skipped. However, if the file is no longer required for a particular release, for example auth_6_0:
Check what symbolic names exist for the file # rlog -h DELETED/ringmenu.src,v Remove any unwanted symbols # rcs -nauth_6_0 DELETED/ringmenu.src,v Check that the symbol 'auth_6_0' was removed # rlog -h DELETED/ringmenu.src,v
7. Remove the file from your project program directory

Civica Pty Limited
# cd `obj`
# rm ringmenu.src
Removing an entire program To remove an entire program directory the procedure is much the same. Ensure none of the files are locked, then at the same level in the file system as the directory, create the DELETED directory and move the directory to be removed into the DELETED directory. 1. In your project, navigate to the directory for the program to be removed, then into the RCS source tree and check none of the files are locked.
# cd i_rt098.4gs # cd `src` # rlock *,v
2. If it does not already exist, create a DELETED directory under the RCS subdirectory:
# cd RCS # mkdir DELETED
3. This step only applies if you are retiring the program from ALL branches: move the program directory into DELETED:
# mv i_rt098.4gs DELETED
4. (ONLY FOR PREVIOUS RELEASES) Remove any unwanted symbolic names from the RCS ',v' file. If the program is still required for prior releases then this step can be skipped. However, if the program is no longer required for a particular release, for example auth_6_0:
Check what symbolic names exist # rlog -h DELETED/i_rt098.4gs/*,v | less If retiring the program from ALL branches, remove unwanted symbols as follows: # rcs -nauth_6_0 DELETED/i_rt098.4gs/*,v (repeat the above instruction for each branch) If retiring the program from nominated branches only, use the following instruction to remove unwanted symbols. This needs to be executed for each source file for the program, and each branch (including trunk if applicable):
# rcs -nauth_6_0 process.src,v # rcs -nauth_6_0 srt098a.trg,v # rcs -nauth_6_0 srt098a.dsp,v # rcs -nauth_6_0 custom.src,v # rcs -nauth_6_1 process.src,v
Developers Manual
Page 16 of 54
Civica Pty Limited
# rcs -nauth_6_1 srt098a.trg,v # rcs -nauth_6_1 srt098a.dsp,v # rcs -nauth_6_1 custom.src,v # rcs -nauth_6_2 process.src,v # rcs -nauth_6_2 srt098a.trg,v # rcs -nauth_6_2 srt098a.dsp,v # rcs -nauth_6_2 custom.src,v # rcs -nauth_6_3 process.src,v # rcs -nauth_6_3 srt098a.trg,v # rcs -nauth_6_3 srt098a.dsp,v # rcs -nauth_6_3 custom.src,v # rcs -ntrunk_20080111 process.src,v # rcs -ntrunk_20080111 srt098a.trg,v # rcs -ntrunk_20080111 custom.src,v # rcs -ntrunk_20080111 srt098a.dsp,v
Check that the symbol was removed (e.g. to check that the symbal: auth_6_0 was removed): # rlog -h DELETED/i_rt098.4gs/*,v | grep auth_6_0
5. Remove the program directory from your PROJECT

# cd `obj` # rm rf i rt098.4gs
Also remove it from every branch for which youre making the program obsolete. 6. In your project, remove the program from the manifest file. The manifest file resides in the Authority root path of your project (i.e. one level up from the application directories).
# rlock MANIFEST_auth (to ensure there are no active locks on the file) # rco l MANIFEST_auth # vi MANIFEST_auth Comment out the entries for the deleted program by pre-ending the entry with a leading minus symbol (-) for example:
Developers Manual
Page 17 of 54
Civica Pty Limited
Check in the change, applying it to all applicable branches e.g.: # btci60 MANIFEST_auth
7. Remove the program from the install database if program to be retired from current release. Add menu maintenance information to the HEAT detail tab for the call to remove program, creating one if necessary.
Developers Manual
Page 18 of 54
Civica Pty Limited
Checking in a new binary file (eg crystal report) To check in a new binary file, first initialize the rcs file with the following:
# rcs i kb <file>
You will be prompted for a description of the file being checked in Then, check the file in as per usual.
# ci u <file>
You will not be prompted for a log this time. NB The descriptions typed in for the Informix version of the report is what will be used for the report lister (see rptlist in the tools section) so should be a well formatted comment that just has the name of the report and a description of what it is. Dont include anything about the version of database, Authority or anything about the call that generated the report. An example of how it should be formatted: Creditors Trial Balance List each creditor and their aged balances. If you need to edit this description to make it fit the format above use: $ rcs -t ci_hr001.rpt # Now you will be asked to enter a description: RCS file: RCS/ci_hr001.rpt,v enter description, terminated with single '.' or end of file: NOTE: This is NOT the log message! >> # to see the description that you just typed in: $ rlog -t ci_hr001.rpt
Recording Tables used in a Crystal Report Each crystal report directory should contain a file with the same name as the directory and .query extension (ie c_dm001.query). This file will contain the sql from the report (and any sub-reports) and it is checked into source control. When you are creating a new report you will need to create a new .query file and from the informix version of the report run the report, go to the Database menu and choose show sql query and copy this into the new file. Then check it into source control as usual. If you are modifying the report in anyway that will effect this sql (ie adding a new table, subreport) then you will need to checkout and update the .query file.
Developers Manual
Page 19 of 54
Civica Pty Limited
What this does is allow us to find crystal reports that reference a table using the whereis script. This is particularly important where a table is to be altered. From the development machine: Use vi to create a new view c_dm001.query and paste in the sql from the report and save. # ci u c_dm001.query you will be asked to enter a comment, enter this: SQL for report c_dm001
Unlocking a specific file revision If a double lock occurs (one in master and one in 6.0) accidentally, you can unlock one of the revisions by doing the following: #rcs -u<Revision Number> <filename>
Compiling a program with an old file revision

To checkout a files revision number to compile the program using the old revision for whatever
reason: rco -r<Revision Number> <filename> Just rco <filename> to take it back to latest revision. CAREFUL DONT CHECK IT IN LIKE THAT
Restoring an old revision permanently To revert a file to a previous revision permanently: rco -l <filename> rco -r<Revision Number> <filename> ci -u <filename> And overwrite writable version.
Developers Manual
Page 20 of 54
Civica Pty Limited
Testpatch
If you have made the same change in both 5.0 and 6.0 you need to run the commands in the lowest release branch i.e. 5.0. However, if you only wish to patch from 6.0, you need to be in 6.0 branch. This will ring true with subsequent releases of 6.1, 6.2 and 6.3 etc. There are a number of items you need to be aware of listed below: Branch Question - After entering your username, a new question is asked:
This is the question that controls whether you patch subsequent branches higher (newer) than the branch you are patching from. For the time being this will have no bearing until 6.0 is released. Priority Question - This will set the QA testing priority in the assignment that auto-generates and you send to QA. If the priority is set to Very Low, the patch will automatically be placed on the test page and therefore should be checked by your Team Leader or BA before being used.
Further Information Prompt
If you enter Y to this prompt, you will be subsequently asked for Also Requires Links, Special Instructions, Additional Information and the Mandatory, Documentation and Test Plan Flags. If you answer with anything else you'll proceed directly to entering the next program identification. Additional Information Question
Information typed here will appear as part of the Issue/Affects/Solution block on the web page. For example:
Program: i_aj001 Version 1.1 Call: 123456 Issue: Request for new functionality throughout Authority to deal directly with the requirements of the new state Department. Affects: NSW Customers Solution: Added functionality to facilitate the information collection requirement for the Department. Additional Information: Added parameter to program to output report file in csv format. Version 1.0 Call: 123456 Issue: Request for new functionality throughout Authority to deal directly with the requirements of the new state Department. Affects: NSW Customers
Developers Manual
Page 21 of 54
Civica Pty Limited
Solution: Added functionality to facilitate the information collection requirement for the Department. Additional Information: Created parameter program for Department functionality. Program: r_aj001 Version 1.0 Call: 123456 Issue: Request for new functionality throughout Authority to deal directly with the requirements of the new state Department. Affects: NSW Customers Solution: Added functionality to facilitate the information collection requirement for the Department. Additional Information: Created report program to output file used by the Department.
Error Messages You must be in a branch to run testpatch. You must be in a release project like /sand/devel/auth_6_0 when you run testpatch. You cannot run testpatch from the master tree. file is out of date (i.e. newer version exists). The file that is checked out is out of date. Bring it up to date by executing: rco file
Developers Manual
Page 22 of 54
Civica Pty Limited
DATABASE ENVIRONMENTS
Any database object changes are now the property of the Development Services Team in Mascot until further notice.
Overview
AUTHORITY runs on multiple database platforms so to support this we have a database for each engine in our environment. In addition to this at each development site we have mirror image databases to allow development on local machines. It is important to keep the schemas of all these database in sync to allow testing on all platforms to takes place and allow cross machine development. The strategy chosen to ensure this happens and to manage the database schema is to store them in a set of files. For most of the files, the contents will consist of simple SQL statements, like create table or create view. These files will be maintained by the developers and kept under RCS. The databases will be synchronised every week as a part of the build (which also synchronises the programs).
Files Location Currently, the master schema files are stored under /sand/devel/$PROJECT/auth/scripts. The structure under the latter is as follows: common/ informix/ Contains scripts that are common to all databases. Contains scripts that are specific to the Informix database or can be automatically converted for Oracle. Files that can be automatically converted are: table.sql index.sql foreign.sql Other files are Informix specific, ie: view.sql (some are in common) procedure.sql check.sql trigger.sql Contains scripts that are specific to the Oracle database. Note that where possible the Oracle scripts are derived from the similarly named Informix scripts. Only the scripts in this directory that are not derived should be maintained
oracle/
Developers Manual
Page 23 of 54
Civica Pty Limited
manually. Currently, the files under those directories are: index.sql procedure.sql trigger.sql check.sql view.sql foreign.sql table.sql storage create index and primary key constraints statements create procedure or create function statements (database specific) create trigger statements (database specific) check constraints statements (database specific) create view statements (some are common others database specific) foreign key constraints create table statements File containing database specific table attributes. The format of this file is database dependent.
Where do I put my SQL All generic table creation statements and indexes should be put in the $APPL/scripts/informix/table.sql and $APPL/scripts/informix/index.sql. All generic view creation statements should be put in the $APPL/scripts/common/view.sql. If specific create statements are necessary for a specific database then these should be put in the view script under that databases directory in addition to the one held under the informix directory. Procedures and triggers are written for each of the supported databases and put into the trigger.sql/procudure.sql under each databases directory.
Developers Manual
Page 24 of 54
Civica Pty Limited
Procedures Schema Migration All changes to the schema for release 6.0 or greater are controlled by the Migrations Generations Engine. Please follow the exact steps below for creations of schema migrations.
Note: You must be logged into vmndev10 to carry out the following steps.
1. Check out the devel branch of the Subversion schema project into your vmndev10 project; if you already have a schema project, you can skip this step.
$ cd /sand/devel/gquinlan $ svn co -q file:///srv/svnroot/authority/schema/devel schema

2. Change into the directory corresponding to the product and release in which you want to introduce your changes:
# Authority 6.2 schema migrations $ cd /sand/devel/gquinlan/schema/authority/6.2 # AWP 6.2 schema migrations $ cd /sand/devel/gquinlan/schema/awp/6.2
3. For Authority migrations, create an sql symbolic link that points to the
$APPL/scripts directory you are making your changes in. Typically this will be your
trunk project:
$ ln -s /sand/devel/gquinlan/auth/scripts sql
For AWP migrations, check out the schema sql scripts from the appropriate Subversion path:
# AWP 62 SQL scripts $ svn co -q file:///srv/svnroot/authority/branches/62/web_platform/iservices/src/release/schema/scripts sql # AWP trunk SQL scripts $ svn co -q file:///srv/svnroot/authority/trunk/web_platform/iservices/src/release/schema/scripts sql
4. Make your changes to the SQL files in the sql directory in the usual way, but do not check them back into RCS or Subversion. 5. Run the miggen command to generate schema migration scripts based on the changes you have made to the SQL files; the syntax is identical to the sync_objects command
Developers Manual
Page 25 of 54
Civica Pty Limited
with the exception that you also need to specify a HEAT call id for each changeset. For example:
$ miggen -i 155056 -T aupywpnz ----------------------------------------------------------------------[[Wed Jun 30 08:15:53 2010] START miggen] ----------------------------------------------------------------------Migrations directory is /sand/devel/gquinlan/schema/authority/6.2 === Fetching latest migrations from SVN... At revision 61146. === Generating schema migration scripts... Created 0426.pl [Create table aupywpnz] Created 0427.pl [Create index aupywpnz_i1] Created 0428.pl [Create primary key constraint aupywpnz_pk] ----------------------------------------------------------------------[[Wed Jun 30 08:15:56 2010] END miggen completed successfully] ----------------------------------------------------------------------Note: miggen will complain if you:
[OK] [OK]
create a table that has no primary key try to add a new column that isn't at the end of an existing table exceed the maximum length of a data dictionary description or label have syntax errors in the SQL file 6. At this point you can either generate more migrations or review the ones you already have. To review, just execute miggen by itself. Notice how the last line tells you what the next step in the process is. This is handy if you are unsure of what to do next:
$ miggen Migrations for release 6.3 are locked by gquinlan@vmndev10 === Generated migrations === Created 0426.pl [Create table aupywpnz] Created 0427.pl [Create index aupywpnz_i1]
Developers Manual
Page 26 of 54
Civica Pty Limited
Created 0428.pl [Create primary key constraint aupywpnz_pk] Total migrations generated: 3 Status: migrations have not been executed; use miggen -x to execute them
7. Before you can commit your new migration scripts to SVN, you must test them on the development databases. To do this, execute:
$ miggen -x ----------------------------------------------------------------------[[Wed Jun 30 08:24:57 2010] START miggen] ----------------------------------------------------------------------Migrations directory is /sand/devel/gquinlan/schema/authority/6.2 ----------------------------------------------------------------------[[Wed Jun 30 08:24:58 2010] Executing migrations on Informix 6.2 development database (aui62dev)] ----------------------------------------------------------------------=== Executing migrations up (to 6.2.0428)... === Executing migrations down (to 6.2.0425)... === Executing migrations up (to 6.2.0428)... [OK] [OK] [OK]
----------------------------------------------------------------------[[Wed Jun 30 08:25:01 2010] Executing migrations on Oracle 6.2 development database (auo62dev)] ----------------------------------------------------------------------=== Executing migrations up (to 6.2.0428)... === Executing migrations down (to 6.2.0425)... === Executing migrations up (to 6.2.0428)... [OK] [OK] [OK]
-----------------------------------------------------------------------
Developers Manual
Page 27 of 54
Civica Pty Limited
[[Wed Jun 30 08:25:05 2010] Executing migrations on SQL Server 6.2 development database (aum62dev)] ----------------------------------------------------------------------=== Executing migrations up (to 6.2.0428)... === Executing migrations down (to 6.2.0425)... === Executing migrations up (to 6.2.0428)... === Execution complete. ----------------------------------------------------------------------[[Wed Jun 30 08:25:08 2010] END miggen completed successfully] ----------------------------------------------------------------------8. If miggen was able to run your migrations successfully, you can check them into SVN using:
[OK] [OK] [OK]
$ miggen -c ----------------------------------------------------------------------[[Wed Jun 30 08:25:49 2010] START miggen] ----------------------------------------------------------------------Migrations directory is /sand/devel/gquinlan/schema/authority/6.2 === Call Id 155056 (3 scripts) === Adding 0426.pl to SVN... === Adding 0427.pl to SVN... === Adding 0428.pl to SVN... === Committing migrations to SVN... === Releasing migrations lock... === Commit complete.
9. Finally, check your SQL file changes back into RCS or Subversion in the usual way. If you need to check the changes back into earlier Authority releases, use the btci command:
[OK] [OK] [OK] [OK] [OK]
$ cd $APPL/scripts/informix $ btci62 table.sql $ btci62 index.sql

For AWP, you will need to use Subversion's merge command.
Developers Manual
Page 28 of 54
Civica Pty Limited
Developers Manual
Page 29 of 54
Civica Pty Limited
Schema Migration - Q & A

Q1. I've generated some schema migration scripts but I need to start over. How do I roll back my work? A1. Use miggen's -u option:
$ miggen -u ----------------------------------------------------------------------[[Wed Jun 30 08:24:05 2010] START miggen] ----------------------------------------------------------------------Migrations directory is /sand/devel/gquinlan/schema/authority/6.2 === Removing 0426.pl... === Removing 0427.pl... === Removing 0428.pl... === Releasing migrations lock... === Undo complete. ----------------------------------------------------------------------[[Wed Jun 30 08:24:06 2010] END miggen completed successfully] ----------------------------------------------------------------------Q2. I checked my SQL changes into RCS without running miggen. Can I still generate the schema migration scripts? A2. Yes; just use miggen's -r option as follows:
[OK] [OK] [OK] [OK]
-r<revision_prior_to_change>:<revision_after_change>
Note that miggen understands the revisions HEAD (last revision on branch) and PREV (second last revision on branch). For example:
$ miggen -i 999 -r1.879:HEAD -T aupywpnz ----------------------------------------------------------------------[[Wed Jul ----------7 22:37:18 2010] START miggen] -------------------------------------------------------------
Developers Manual
Page 30 of 54
Civica Pty Limited
Migrations directory is /sand/devel/gquinlan/schema/authority/6.2 === Fetching latest migrations from SVN... At revision 61430. === Generating schema migration scripts... Created 0426.pl [Create table aupywpnz] Created 0427.pl [Create index aupywpnz_i1] Created 0428.pl [Create primary key constraint aupywpnz_pk] ----------------------------------------------------------------------[[Wed Jul successfully] ----------------------------------------------------------------------Q3. How can I query the database to check my schema changes? A3. Use the ddl command:
[OK] [OK]
7 22:37:21 2010] END miggen completed
$ ddl -c aui62dev aupywpnz -- Database is aui62dev (schema version 6.2.0428) -- Informix 6.2 development -- EFT data for NZ CREATE TABLE aupywpnz ( key_num SERIAL NOT NULL, Number emp_num INTEGER NOT NULL, Employee Number pay_cyc SMALLINT, Cycle tax_yer SMALLINT, Year pay_prd SMALLINT, Period dta_txt CHAR(180) ); CREATE UNIQUE INDEX aupywpnz_i1 ON aupywpnz ( key_num Number -- Key -- Data -- Pay -- Tax -- Pay --- Key
Developers Manual
Page 31 of 54
Civica Pty Limited
); ALTER TABLE aupywpnz ADD CONSTRAINT PRIMARY KEY ( key_num Number ) CONSTRAINT aupywpnz_pk;
Q4. How can I see what databases I can connect to using the above ddl command? A4. Use the ddl -c? command:
-- Key
$ ddl -c? amiqa6 esmtrunkreg ammqa6 eso60dev ammtrunkdev eso61dev aui50dev eso62dev aui60dev aui61dev esotrunkdev aui62dev auicustomer moicustomer auiinst auimigrate moimastdev auiqa4 auiqa5 mom60int auiqa6 mom61int auiqa7 auitrunkdev momtrunkint aum50dev aum60dev aum60int aum60reg aum61dev ifx auomastdev auoqa7 auotrunkdev esi50dev esi60dev esmcustomer esmqa4 esmqa5 esmqa6 esmqa6_gqtest moogb1 saigb1 samgb1 saogb1 schemaauo62dev auo9dev esm62int esm62reg momgb1 auo61dev esm62dev auo50dev auo60dev esm61int esm61reg moiqa5 aumtrunkint aumtrunkreg esm60reg esm61dev moigb1 aumqa7 aumtrunkdev esm60dev esm60int heatsql aumqa5 aumqa6 esiqa7 esitrunkdev esoqa7 aumqa4 esiqa6 aumcustomer esiqa5 aum62reg esiqa4 aum62int esimigrate
Developers Manual
Page 32 of 54
Civica Pty Limited
aum61int msv aum61reg ora aum62dev
esi62dev esicustomer esiinst
esmqa7 esmtrunkdev esmtrunkint
schemaschema-
Q5. How can I reserve migration numbers so they won't be used by miggen? A5. Edit the file etc/reserved_mignums in the schema/<product>/<release> directory where you are running miggen. Add a line specifying the migration numbers you want to reserve. For example:
426..428
means "reserve the numbers 426, 427, 428". If you want to make your changes visible to other miggen users, check the updated file back into SVN. The ability to reserve migration numbers is especially useful if you are creating data migrations and you don't want someone else to steal the migration numbers you are using. Q6. How can I generate a report that summarises the migrations either for a specific release or all releases? A6. Use the miginfo command: To summarise migrations for a specific product release:
$ cd /sand/devel/gquinlan/schema/authority/6.2 $ miginfo | less 6.2/0001.pl DDL 6.2/0002.pl DDL aupraddr] 6.2/0003.pl DDL aupraddr_i1] ...[snip]... 6.2/0432.pl DML 6.2/0433.pl DML aumncmnd aumncmnd [aumncmnd: update [aumncmnd: update cmd_lne r_as016.4gs to r_as019.4gs] cmd_lne i_as040.4gs to i_as048.4gs] Total DDL: 302 Total DML: 119
To summarise migrations for all product releases:
aualtdsc aualtdsc aupraddr aupraddr
[Create view avwnmemo] [Create table [Create index
$ cd /sand/devel/gquinlan/schema/authority $ miginfo | less 5.0/0001.pl DDL av_car_worksheet] 5.0/0002.pl DDL av_car_worksheet] aualtdsc [Create view aualtdsc [Drop view
Developers Manual
Page 33 of 54
Civica Pty Limited
5.0/0003.pl DDL av_am_inspections] ...[snip]... 6.3/0095.pl DML 6.3/0096.pl DML
aualtdsc
[Drop view
aualrefn aualrefn
[aualrefn: insert [aualrefn: insert
ref_typ = 'not_fld' and rev_val = 261 row] ref_typ = 'wbn_fld' and ref_val = 229 row] Total DDL: Total DML: 79 15 # find all DDL scripts # find all DML scripts # find migrations that modify
miginfo also has the ability to search for specific changes: $ miginfo -m DDL $ miginfo -m DML $ miginfo -n aupypost aupypost
Q7. When I run miggen, I get a complaint about the description length being too long. For example:
/sand/devel/master/auth/scripts/common/view-r1.226.sql(8838): The #-description length (68) is too long. Use the ^ markers below to shorten the length to 50 characters or less: view to be used for warning memos to give all links between modules. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ...[snip]... +--> ERROR <---------------------------------------------------------+ | Failed to parse /sand/devel/master/auth/scripts/common/view| | r1.226.sql | +--------------------------------------------------------------------+
How do I fix this? A7. You'll need to perform the following actions: 1) If you have made lots of changes, save them by renaming your file. For example:
cd $APPL/scripts/common mv view.sql view-mychanges.sql

2) Check out your file for editing again. For example:
rco -l view.sql
Civica Pty Limited
Answer y if RCS warns you about clobbering a writable file. 3) Shorten the description miggen is complaining about. You can use the line number referred to in the error message to go directly to the offending line. 4) Check the updated file back into RCS:
ci -u view.sql
5) Check out your file for editing again.
rco -l view.sql
6) Use the backup you made in step 1 to paste your original changes into the new version of the file and run
miggen
again.
Note: Make sure you do not copy the revision id $Id: from the back up. If you do you will have to update the revision id to reflect the current head of the trunk or branch. Q8. When I run miggen, I get a complaint about the target release being incorrect. For example:
$ miggen -i 130890 -V av_document_names You are in the 6.2 migrations directory but the target release for call id 130890 is 6.4; please change to the 6.4 directory and run miggen from there.
What do I do? A8. This occurs when the minimum release for the call is left blank in HEAT: in this case,
miggen assumes the target release is whatever the trunk (i.e. next) release is. You will
need to get Vikki Shedden to update the minimum release. The reason behind this is to prevent schema changes in existing releases unless approved by Vikki.
Developers Manual
Page 35 of 54
Civica Pty Limited
Development Process
TOOLS
AUTHORITY Scripts
Program Listing From a unix prompt it is possible to list out all the programs in Authority, or for a module or for a specific set of programs. The syntax for the command is: proglist [module] [start of program(optional)] Use % for wildcard. Arguments default to *. For example: To print a list of all programs: 'proglist' To print a list of all GL programs: 'proglist gl' To print a list of all reports: 'proglist % r' To print a list of all GL reports in the 900 numbers: 'proglist gl r_gl9' Typing proglist h will give you this information from the prompt. Program Name To find the name of a program, use the progname script as follows: 1. cd to a program directory ie cd i_br002 2. type progname i_br002 This will show the following: i_br002.4gs Report Listing From a unix prompt it is possible to get a list of the reports (both crystal and 4GL) for the branch you are in. Here is a script that you can use to find your reports that may have 'initial revision' as their comment if you want to fix them. If it is easier then use the -mMODULE switch to do it module at a time. The syntax for the command is: title = "Bank Reconciliation Entry"
Developers Manual
Page 36 of 54
Sanderson
AUTHORITY
rptlist -h # Show this usage message rptlist <options> where <options> are: -d # Show report file paths only (for debugging) -m<module> # Show reports for <module> only: e.g. gl -r<project> # Traverse <project> tree: default is master For example: # Give me a list of the GL reports in the master tree $ rptlist -mgl # -mGL also works c_gl001.4gs Crystal Report - Activity Balances (IFX) c_gl002.4gs Crystal Report - Chart of Accounts (IFX) r_gl001.4gs General Ledger Standard Descriptions ...... # Give me a list of the PC reports in the auth_4_6 tree $ rptlist -mpc -rauth_4_6 ....... c_pc005.4gs Crystal Report - Project Cost Balance Listing with Drill Down(IFX) c_pc006.4gs Informix version of Project Costing to General Ledger Exception report c_pc007.4gs Informix version of Project Costing to General Ledger Comparison report r_pc001.4gs Project Costing Account Descriptions r_pc002.4gs Project Cost History Listing..... # Same as above but just show the report paths (useful for debugging) $ rptlist -mpc -rauth_6_0 -d pc.4gm/c_pc001.4gs/ci_pc001.rpt pc.4gm/c_pc002.4gs/ci_pc002.rpt...... An alternative is to use this web site: http://georgeq/ Use the Utilities link and choose List Authority Reports. Schema Listing To print a listing of the database, type the following: table tablename <enter> To list all the tables for a module, enter the first four characters, followed by an asterisk (wildcard character). For example, to list all the payroll module tables, the table name would be aupy*.
Developers Manual 13 August, 2009
Page 37
Sanderson
AUTHORITY
Running a program NOTE: GDC has to run on port 6500 for auth50 and 6400 for auth60 "C:\Program Files\FourJs\gdcax\bin\gdc.exe" -M -D -p6500 See the wiki for more info and how to setup for msv. https://staff.authority.civica.com.au/staff/secure/techwiki/Wiki.jsp?page=Configurin gYourPC To run the program from within its directory: cd $projectName cd programName
% doit <enter> To run the program from another directory( eg: to run program i_ap001): % doit i_ap001 <enter> Output Debug Files Debug statements can be coded into a file, like this: call errorlog(Print this and the variable below) call errorlog(g_variable clipped) doit vi errlog Debugger Basic Debugging
cd $projectName cd programName vi the 4gl and find the line number or function name you want to stop at. wacrun d programName or gdebug programName (may or may not work)
Page 38
Sanderson
AUTHORITY
(fgldb) prompt. From here you can do the following: br functionName br custom:110 br custom:110 if m_rtmast.ass_num = 123 run <program arguments if applicable> trm_num 1 (eg run trigger_argument_1 staffonly trm_num1) Set variable g_variable = value p g_variable (prints the value) s = step into l (or list) = displays about 10 lines of code around where you currently are co = continues until programs finished or breakpoint.
Graphical Debugger To use the debugger go to the program you wish to debug and type 'wacdb.sh': cd i_al001 wacdb.sh Or type `gwacdb followed by the program name: cd i_al001 gwacdb i_al001 You should see a 4GL screen appear with the cursor sitting in a text dialogue labelled '(fgldb)'. The main gotcha is to remember to use F12 for accept or OK rather than the main keyboard "Return/Enter" key. Try the following: (fgldb) help F12 (fgldb) br forminit:135 F12 (fgldb) snoop scratch F12 (fgldb) r trm_num 1 F12 (fgldb) F3 (fgldb) F3 (fgldb) F3 (fgldb) F3 (fgldb) F3 (fgldb) F3 (fgldb) F5 (fgldb) q F12 Commands available break bp continue delete Set breakpoint at specified line or function List Breakpoints/Watchpoints Continue program being debugged Delete some breakpoints
Page 39
Sanderson
AUTHORITY
disable down enable help finish let leta next print quit run
Disable some breakpoints Select and print FUNCTION called by this one Enable some breakpoints Display this Help (F1) Execute until selected stack frame returns. Set value of program variable Set subscript value of program variable. Must Quote Value in '' eg. leta rw500.instal_flags[49]='3' Step program, proceeding through subroutine calls (F2) Print value of expression Exit fgldb Start debugged program
NOTE: You can send the process of the program being debugged the SIGINT signal to break the program while it is executing NOTE: If a file called 'wacdb.cmds' exists in the current directory, each line in the file will be processed as a command when starting the debugger grep
grep n (prints the line number) i (ignores case) *.4gl
Hiding or Inactivating Fields, Sections

The basic two dom commands are to hide or activate. These used in conjunction with what youre trying to hide To hide specific field: call dom_set_hidden(dom_find_fields("fld_nme"), true) To display a specific field that has been hidden: call dom_set_hidden(dom_find_fields("fld_nme"), false) To inactivate a field: call dom_set_active(dom_find_fields("fld_nme"), false) To reactivate an inactive field: call dom_set_active(dom_find_fields("fld_nme"), true) To hide pages (tabs): call dom_set_hidden(dom_find_pages("CRM Options"), true) To display pages (tabs):
Page 40
Sanderson
AUTHORITY
call dom_set_hidden(dom_find_pages("CRM Options"), false) To hide groups: call dom_set_hidden(dom_find_groups("Animal Check Options"), true) To display groups: call dom_set_hidden(dom_find_groups("Animal Check Options"), false)
Whereis
This searches the authority $APPL directory or a specific modular directory (*.4gm specified by the two character module id) for programs containing the specified string. Output is directed to the screen, unless the >filename.txt option is used (directs to the file).
For example
% whereis String --Searching for a string in the whole the $APPL structure eg % whereis auanmast % whereis Sting module-id --Searching for a string in a particular modular directory (*4gm) eg % whereis auanmast an % whereis String module-id >filename.txt Redirect output to a file eg % whereis auanmast an > animal.txt
NB This search also includes the crystal reports (.rpt files) stored either in the $APPL/crystal directory or within the modular directories (*.4gm) and the scripts used to create tables, triggers and procedures used by Authority or third party products. The result of the search will list the module, program and file that the string was located in eg: whereis: searching for auanmast Commenced searching at /sand/devel/master/auth Fri Mar 15 11:00:45 EDT 2002 Module Program File ------- ----------- -------------integration/mapinfo/auandetv.sql scripts/informix/table.sql .. an.4gm/c_an004.4gs/ci_an004.rpt . an.4gm/i_an018.4gs/globals.org .
--Third party integration script --Authority database script --Crystal report within an module --Authority program
Page 41
Civica Pty Limited
SQL Explain
Informix has a tool called SQL explain that can be run to determine how the data is being accessed. The query optimiser formulates a query plan to fetch the data rows that are required to process a query. Results from the sql explain may vary across server environments. Some of the factors that determine these variances are: 1. The number of I/O requests that are associated with each file-system access. 2. The CPU work that is required to determine which rows meet the query predicate. 3. The resources that are required to sort or group the data. 4. The amount of memory available for the query (specified by the DS_TOTAL_MEMORY and DS_MAX_QUERIES parameters.) This tool can be used via Dbaccess or when running an Authority program. For an Authority program, a -explain suffix is required to be added. Eg: 1. Change directory to that program. 2. cd $APPL/gl.4gm/i_gl015.4gs 3. wacrun i_gl015 trm_num 1 explain On UNIX, by default the output from explain will be written to the sqlexplain.out file. From Dbaccess, the set explain command can be turned off and on as required. Eg: 1. Select Query Language>Database>New 2. set explain on; 3. select blah from table blah. The output from explain will reside in a file named sqlexplain.out in the directory where dbaccess was commenced. Each subsequent query will be appended to that file. NB: The sqlexplain.out file can become quite large and it is recommended that it is removed before the program is run again using the explain option.
4 July 2011
Page 42 of 54
Civica Pty Limited
Make sure that write permission exists in the directory where the sqlexplain.out file is to be written.
When a program is running slow, sql explain will sometimes help to identify where indexes are not getting used to their optimum potential. The output from the explain will contain the following information: 1. The SELECT statement for the query, 2. As estimate of the query cost in units used by the optimiser to compare plans. These units represent a relative time for query execution, where each unit is assumed to be roughly equivalent to a typical disk access. The optimiser chose this query plan because the estimated cost for its execution was the lowest among all the evaluated plans. 3. An estimate for the number of rows that the query is expected to produce. 4. The order to access the tables during execution. 5. The access plan by which the database server reads each table. 6. The table column or columns that serve as a filter, if any and whether the filtering occurs through an index. 7. The join plan for each pair of tables. The following table shows the possible access plans: Access Plan SEQUENTIAL SCAN INDEX PATH AUTOINDEX PATH Effect Reads rows in sequence Scans one or more indexes Creates a temporary index
The sqlexplain.out file is examined firstly for SEQUENTIAL SCAN. This is the simplest method used to access a table. The optimiser chooses this method when most of the table must be read, or the table does not have an index that is useful for the query. Note, that sometimes a sequential scan is just as quick as using the index depending on the amount of data in the table. Eg: QUERY: -----select * from auglfund where fnd_num = ? Estimated Cost: 2 Estimated # of Rows Returned: 1 1) auth.auglfund: SEQUENTIAL SCAN
4 July 2011
Page 43 of 54
Civica Pty Limited
Filters: auth.auglfund.fnd_num = 1
In this example, as there are only 4 rows on this table, forcing the program to use the index will not increase the speed.
Another area to observe in the output is a high Estimated Cost. A high cost for a low return may point to a problem, ie the incorrect use of an index or primary table. If the estimate outweighs the returned rows in the table, this may also point to the same problem. The estimated cost is not an exact measure but it can highlight an issue.
WACGEN
WACGEN is a tool that generates informix 4GL code from a screen design. It is a derivative of Informix FOURGEN written by Andrew Clarke from the Hurstville office. This manual contains all the specific functionality available in the WACGEN product. It should be used in conjunction with the Informix 4GL and FOURGEN manuals (Physical copies held in each office) \\civnfile\Document\Development Team Mgt\Tools\WACGEN.doc 4JS Visit the website for up to date information regarding this, our version will continually change over time. http://www.4js.com/exclude/en/html/fgl/
TECH WIKI
https://staff.authority.civica.com.au/staff/secure/techwiki/
4 July 2011
Page 44 of 54
Civica Pty Limited
APPENDIX 1: DATABASE COLUMN ABBREVIATIONS

acc acr acq atv act add ad1 ad2 ad3 ad4 adv age als alo alw alp alt amt ana apl apr app arc ass ast ath aut avl avg awr bak bal bnk bsb bse bat bll brt blo blk bok brn bgt bld bus buy account accural acquisition activity actual address address line 1 address line 2 address line 3 address line 4 advance age alias allotment allowed/ed/anoe alpha alternate amount analysis application appraisal approve/d/al archive assessment asset author/ty/zation automatic available average award back/order balance bank bank ref base batch bill birth blanket order block book branch budget building business buy cnc cpt civ csh ctg crt chr chg cht chk chq cld cis cty clm cls cde cmm com cmp cop cml cmt con cta ctr cti ctl cvy cst cog cnt cou cnt crs cvr cre crm crd crn crr cur cas cus cyc cancel capital capital improved cash category certificate character charge/d chattels check cheque child cistern city claim/ed class/ification code commission communication company compensation complet/e/ion confere/nce construct/ion/ed contact contract contribution control convey/ance cost cost of goods count country county course cover create/d credit memo credit/or crown currency current current assets customer cycle
4 July 2011
Page 45 of 54
Civica Pty Limited
dmg dat dte dys dth dbt drm deb dcl ded dfl dfr del dpt dep dpo dpr dsc dif dis dst dvs dok doc
dox
damages data date days death debit debit memo debitor declare/ation deduction default defere delete department deposit/or depot depreciation description different/tion/ce discount distribution division docket document
document exchange number
fnc fin frs fxd fas flg fol fro fmt frm frw frg frq ful fnd gas gen giv gv1 gv2 gds grn gar hel hir hst hld hol hme hrs hou idn inc icr idx inf ini ins isr int itr ivy inv iss itm job jrn key kms
finance finish first fixed fixed assets flag folio forecast format formula forward freight frequency full fund gas general given given name 1 given name 2 goods grant/ed guarantee health hire history hold holiday/s home hours house identifi/er/cation income increase index inform/ation initial/s instalment insurance interest internal inventory invoice issue/d item job journal key kilometers
dit due drt ern eas edt elo ele emp emr end enq ent eti est exs xit exp exi ext fct fam fax fld fle fnl
double time due duration earnings east edit elector/al electricity employee employer end enquiry entered entitlement estimate/d excess exit expense expiry extention factor family fascimile field file final
4 July 2011
Page 46 of 54
Civica Pty Limited
lbl lbr lev

lno lpf
label labour leave

letter non-compliance letter of program fault
nte num off onc obl opr ord org ori ovt ovd ovh own pgr prm prt pye pym pay pen per prd pr1 pr2 pr3 ptd
ppy
note number officer oncost opening balance operator order organisation original over time overdue overheads owner pager number parameter part paye tax payment payroll pension/er percentage period period 1 period 2 period 3 period to date
periodical payment
lvy lia lcn lfe lmt lin lnk lqd lst lod lcl lct lgf lng
lsl ltl
levy liability licence life limit line link liquid list loading local location log file long
long service leave long term liabilities
lok lot mng mnl mar mss mst mtr max mmo mem mto mdl min mco mph mod mdu mth mtd mlt nme nm1 nm2 nar ntn net nav nml nor
look lot manage/ment manual marital mass master materials maximum memo memorial method middle minimum miscellaneous mobile telephone modification module month month to date multipl/e/y name name 1 name 2 name and address nation/ality net net annual value normal north
pmt psn phy pck pln pla plu pol pos pod pst pre pps pri pcd prn prt pro pft prg pjr prp pub pli pu
permit person physical pick/ed plan plant plural policy position post code post/al premium prescribed payment scheme price prime cost adjustments principal print product profit program project property public public libility purchase
4 July 2011
Page 47 of 54
Civica Pty Limited
qua qty qtr rte rdy rsn reb rec rcv rcd rcr ref rgn reg rgl rem rls rlg rqd req res rsp rsl rtr rtn ret rvw roa rmb rol sal sls slp slv smp scl sch ser sec sty sel snr sep spt seq srl srv stl sex sht shp sik
quality quantity quarter rate ready reason rebate receipt received record recurring reference region register regulation reimbursement release religion required requisition residential responsible result retire/ment return return review road road side mail box roll salary sales salesperson salvage sample scale scheme search section security sell senior/ity separate septic sequence serial service settlement sex sheet ship/ment sick
sig sng ste stv svd skl sld sth spc ssa stf std sta stt stu stk str sub sdv sbr sps sup sur tag tak tnk tax phn ph1 ph2 trm tmd tme ttl trd trn typ ucv unn unt use utl vac val vrt vnd vol wgs whs wrr
sign/ature single site site value site visitation docket skill sold south special ssf appendix staff standard state statistic/al/ally status stock street sub account , total subdivision suburb supplementary rate supplier surname tag taken tank tax telephone telephone 1 telephone 2 term/s terminated time title trade transaction type unimproved union unit use/age utility vacation value/ation variation vendor volume wages warehouse warrant/y
4 July 2011
Page 48 of 54
Civica Pty Limited
wgh wst wth wrk wok yer ytd zro zne
weight west with work/er workers compensation year year to date zero zone
4 July 2011
Page 49 of 54
Civica Pty Limited
AUTHORITY
APPENDIX 2: MODULES BY KNOWLEDGE CENTRE

Knowledge Centre Finance Module Ref AP AS BR CW GL HR IC IR LN NR PC PL PU PY RA TR AN AR BL DE EL HI IN MA PR RE RT SR WB WO Module Name Accounts Payable Assets Bank Reconciliations Cheque Writing General Ledger Human Resources Inventory Control Investment Register Loans Name and Address Register Project Costing Plant Purchasing Payroll Roads and Traffic Trusts Companion Animals Accounts Receivable By Laws Debt Recovery Elections Hierarchy Infringements Major Agents Property Receipting Rates Streets Water Billing Work Orders
Revenue
Developers Manual 29 September 2004
Page 50

Developers Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Developers Manual

Uploaded by

Copyright:

Available Formats

Developers Manual

Revision History Date Version No. Author Description

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Robert Davies Robert Davies

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Program group level.

.dsp (layout) .trg (code)

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

# rco -r<Revision Number> <filename>

Just rco <filename> to take it back to latest revision.

To revert a file to a previous revision permanently:

And overwrite writable version.

Authority Developers Manual

Civica Pty Limited

Check out the source file you need to change

Authority Developers Manual

Civica Pty Limited

And remove the branch direcory

For a further description of btci options type the following command:

Adding a new program to a previous branch

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

3. Create a deleted directory in RCS

5. Change the owner

7. Remove the file from your project program directory

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

5. Remove the program directory from your PROJECT

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Authority Developers Manual

Civica Pty Limited

Compiling a program with an old file revision

Authority Developers Manual

Civica Pty Limited

Further Information Prompt

Authority Developers Manual