SysWorks

Application Development Guide

Order Number: SWRK-ADG-35

August 2009

This manual describes and provides reference information on how to use SysWorks to develop and maintain applications.

Revision/Update Information: This manual supercedes the SysWorks^tm V3.4-1 Application Development Guide

Operation System and Version: OpenVMS VAX V7.2 or higher;
OpenVMS Alpha V7.2 or higher;
DECwindows/Motif V1.2-3 or higher

Software Version: SysWorks^tm V3.5

Copyright ©1987 - 2009 Corpita Pty Ltd

Printed in Australia

The following are trademarks of Compaq Computer Corporation: ACMS, ALL-IN-1, AXP, BASIC, Bookreader, CDA, CI, DATATRIEVE, DBMS, DDIF, DEC, DEC ACCESSWORKS, DEC Ada, DEC C, DEC Fortran, DEC Pascal, DECdecision, DECdesign, DECdirect, DECdns, DECdocument, DECdtm, DECforms, DECimage, DECintact, DECmigrate, DECnet, DECnet/OSI, DECset, DECsupport, DECtp, DECwindows, Digital, DTIF, EDT, HSC, MASSBUS, MicroVAX, MicroVAX II, MSCP, OpenVMS, OpenVMS Cluster, RA, StorageWorks, TA, TMSCP, TURBOchannel, ULTRIX, VAX, VAX C, VAX MACRO, VAX-11/780, VAXcluster, VAXELN, VAXft, VAXstation, VIDA, VMS, VMScluster, VT100, and the DIGITAL logo.

PostScript is a registered trademark of Adobe Systems Inc.

Motif is a registered trademark of Open Software Foundation, Inc.

Oracle is a registered trademark, and Oracle CDD/Repository, Oracle CODASYL DBMS, Oracle Expert, Oracle Rally, Oracle Rdb, Oracle Trace and Rdb7 are trademarks of Oracle Corporation.

OSI is a registered trademark of CA Management, Inc

All other trademarks and registered trademarks are the property of their respective holders.

This document was prepared using DECdocument V3.3.

Contents Index

Preface

We welcome your comments on this manual or any SysWorks manual. If you have suggestions for improvements or find any errors, please indicate the chapter, section and page number (if available). Your input is valuable in improving future releases of our documentation.

You can send comments to us in the following ways:

Email---http://www.sysworks.com.au/contact.php
Phone---+61 (03) 9411 4411
FAX ---+61 (03) 9411 4499

Postal service

SysWorks Corpita Pty Ltd 15 Bedford Street Collingwood VIC 3066 Australia

This manual describes and provides reference information on how to use SysWorks^tm to develop and maintain applications.

Intended Audience

This manual is intended for SysWorks^tm users who have a working knowledge of the underlying Digital products.

Conventions

The following conventions are used in this document:

Conventions Description

[Ctrl/X] A sequence such as [Ctrl/X] indicates that you must hold down the key labeled [Ctrl] while you press another key or a pointing device button.

[] In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one or all of the choices.
In system prompts indicates the default value which will be assumed if the Return key is pressed without first entering a value.

{} In format descriptions, braces surround a required choice of options; you must choose one of the options listed.

| In format descriptions, vertical bars separate the options. If the options are enclosed in brackets (i.e. []) you can select none, one or all of the choices. If the options are enclosed in braces (i.e. {}) you must choose one of the options listed.

() In system prompts, parenthesis indicate the list of values one of which may be entered. The values are separated by a forward slash "/"

... An elipsis indicates that a value within a range may be chosen or a syntax repeated. A range may be indicated by a pair of end values, or an end value and an end keyword. For example Disk quota (0..unlimited) indicates that the keyword unlimited may be used to represent the highest possible disk quota.

italic text Italicized words and letters indicate that you should substitute a word or value of your choice.

UPPERCASE TEXT Uppercase letters indicate the name of a command or routine.

monospace text Normal monospace text indicates system prompts and output.

bold monospace text Bold monospace text indicates user responses to system prompts.

bold monospace italic text Bold monospace italic text indicates user responses to system prompts which need approriate value substitution.

mouse The term mouse is used to refer to any pointing device such as a mouse, a puck or a stylus.

MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)

Conventions	Description
`[Ctrl/X]`	A sequence such as `[Ctrl/X]` indicates that you must hold down the key labeled `[Ctrl]` while you press another key or a pointing device button.
[]	In format descriptions, brackets indicate that whatever is enclosed is optional; you can select none, one or all of the choices. In system prompts indicates the default value which will be assumed if the Return key is pressed without first entering a value.
{}	In format descriptions, braces surround a required choice of options; you must choose one of the options listed.
\|	In format descriptions, vertical bars separate the options. If the options are enclosed in brackets (i.e. []) you can select none, one or all of the choices. If the options are enclosed in braces (i.e. {}) you must choose one of the options listed.
()	In system prompts, parenthesis indicate the list of values one of which may be entered. The values are separated by a forward slash "/"
...	An elipsis indicates that a value within a range may be chosen or a syntax repeated. A range may be indicated by a pair of end values, or an end value and an end keyword. For example Disk quota (0..unlimited) indicates that the keyword unlimited may be used to represent the highest possible disk quota.
italic text	Italicized words and letters indicate that you should substitute a word or value of your choice.
UPPERCASE TEXT	Uppercase letters indicate the name of a command or routine.
monospace text	Normal monospace text indicates system prompts and output.
bold monospace text	Bold monospace text indicates user responses to system prompts.
bold monospace italic text	Bold monospace italic text indicates user responses to system prompts which need approriate value substitution.
mouse	The term mouse is used to refer to any pointing device such as a mouse, a puck or a stylus.
MB1, MB2, MB3	MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The buttons can be redefined by the user.)

Unless otherwise noted, all numeric values are represented in decimal notation.

Chapter 1
Overview

This chapter provides an overview of developing applications using SysWorks^tm.

When SysWorks^tm is installed at a system of turnkey level and is used to create an application environment, various OpenVMS authorisation and disk structures are created. If SysWorks^tm is not used to create these structures, they have to be created manually or by other site specific means. See Chapter 11 for details about what structures need to be created and how this may be done.

1.1 Environments

Each application is developed and maintained in a set of environments.

When CMS is used, a common CMS library contains a class for each environment. See Section 3.3 for more details. The following sections describe each of the standard application development environments.

1.1.1 Common

The fixed code for the common environment is APPL.

1.1.2 Pre-Devlopment

The default code for the pre or future development environment is FDEV. Other codes used include DDEV.

1.1.3 Development

The default code for the development environment is DEV. Other codes used include DEVL.

1.1.4 Development Testing

The default code for the development testing environment is DTST.

1.1.5 Maintenance

The default code for the maintenance environment is MNT. Other codes used include MAINT.

1.1.6 Maintenance Testing

The default code for the maintenance testing environment is MTST.

1.1.7 Production

The default code for the production environment is PROD. Other codes used include PRD.

1.1.8 Training

The default code for the training environment is TRNG.

1.2 Moving between Applications and Environments

After logging in to a cluster, the first command to use to access the application development sub-system is the CONTEXT APPLICATION command. In full SysWorks^tm environments, the symbol that implements this command is defined at login time. In private SysWorks^tm environments, the user needs to ensure that this symbol (and any others referred to in this guide) are defined. The most common way to define these symbols is by executing SWRK_SFT_DIR:SYLOGIN.COM. If in doubt, consult your site manager for the definition of the SWRK_SFT_DIR logical name. The CONTEXT APPLICATION command performs various actions required to `move' the user to the application environment. See the command dictionary for full details on this command. One of the actions performed is changing the users default device and directory.

1.2.1 LOGICALS.COM

An application environment's LOGICALS.COM command procedure is used to define application logical names. In a full SysWorks^tm installation, this procedure is normally executed under the application environment's username at system startup or disk mount time, and populates a system wide logical name table. It is also executed by the CONTEXT APPLICATION , CONTEXT ENVIRONMENT or CONTEXT VERSION commands if the application environment about to be entered does not have populated logical name table. If the logical name tables does not exist, these commands create a process logical name table - see section Chapter 2 for more details.

1.2.2 ENTER.COM

This command procedure is executed after other actions of the CONTEXT APPLICATION , CONTEXT ENVIRONMENT or CONTEXT VERSION commands have been completed. It is associated with the context in effect after the move takes place.

It is used to create DCL symbols and define process and job logical names. These logical name definitions are required because some products (eg. ACMS task group debugging) need logicals to be in the job table rather than the application environment table.

1.2.3 EXIT.COM

This command procedure is executed before other actions of the CONTEXT APPLICATION , CONTEXT ENVIRONMENT or CONTEXT VERSION commands. It is associated with the context in effect before the move takes place.

All actions taken in an applications ENTER.COM should be reversed in its EXIT.COM. It should delete DCL symbols created in, and deassign logicals defined in the corresponding ENTER.COM. There is no need to deassign logical names in the application environment logical name table because it is `hidden' when the application environment is not in use.

Chapter 2
Logical Names and Logical Name Tables

Each application environment uses a logical name table. The name of this table has the form LNM_appl_envr.

If SysWorks^tm is installed at the system level or above, this table would normally be a system wide table. In private installations, it would normally be a process logical name table. In either case, if there is no process or system logical name table when a CONTEXT APPLICATION , CONTEXT ENVIRONMENT or CONTEXT VERSION command is used, a process or system wide logical name table will be created depending on the developers privileges.

2.1 Common and Specific Contexts

Some application environments support the both a common and specific context. These environments are typicall the development and maintenance style environments. Testing and production style environments normally support only the common context.

2.1.1 Common

In the common context, all users share the application environments common directory structure such as software, data, library and work directories. Compiling and building under the common context causes the new versions to be seen by all other users and developers who are also using the common context.

2.1.2 Specifc

In the specific context, users have private versions of software and/or data on which they are working. This is achieved by making many of the standard application logicals search list in the users job logical name table. These search lists are designed to use the users private version first, and if that is not present, to use the common version.

Table 2-1 describes the objects for which search lists may be defined.

Table 2-1 Specific Context Search Lists
Object Job Logical Name Usage

CDD/Repository default Includes a USER. user directory before the root directory.

CMS Class Path If the common CMS path does not specify the latest generation, includes a user specific path before the common path. See Section 3.3 for more details.

The following directories:

Data
Library
Runtime
Software
Work
For each of these directories a user sub-directory of the associated common directory or, if that is not present, the users work sub-directory, is included.

**Table 2-1 Specific Context Search Lists**
Object	Job Logical Name Usage
CDD/Repository default	Includes a USER. user directory before the root directory.
CMS Class Path	If the common CMS path does not specify the latest generation, includes a user specific path before the common path. See Section 3.3 for more details.
The following directories: Data Library Runtime Software Work	For each of these directories a user sub-directory of the associated common directory or, if that is not present, the users work sub-directory, is included.

Chapter 3
Source Control

This chapter describes the source control facilities provided by SysWorks. At this time SysWorks only uses CMS for source control.

Each application has at least one application common CMS library.

3.1 CMS Libraries

SysWorks supports a common CMS library for all environments of an application. This CMS library must be located in the APPL environment (eg. DISK_APPL:[appl.SRC.CMSLIB]). Each environment is represented by a CMS class within the library.

By default, the class names are of the form appl_envr. For example, the XYZ_DEV class would contain the development generations of the XYZ application's source.

The system also supports optional separate CMS libraries for development and requires them pre or future development environments (eg. DISK_DEV:[appl.SRC.CMSLIB]). These CMS libraries should still contain the appropriate classes.

One of the primary reasons for supporting these split CMS libraries is performance. Having multiple CMS libraries reduces locking, both at a CMS level and a disk level.

3.2 Application Common CMS Library

This CMS library resides in the common area of the application. For example the CMS library for the FIN application would reside in:

DISK_APPL:[FIN.SRC.CMSLIB]

No reference directory is used as the application environment work directories effectively become the copy of the appropriate generations.

3.3 Classes and Generations

In the common CMS library there is a class for each application environment and application release. These classes have names of the format appl_envr and appl_vrsn. For example FIN_DEV might represent the financial application development environment class, and FIN_V010 might represent the production version V1.0 of the application.

Table 3-1 lists the various environments and their use of CMS. The following should be noted:

The mainline or variant generations only apply in the common CMS library.
Future development environments do not have an associated class in the common CMS library.
When a development or maintenance environment has its own local CMS library:
- Mainline generations are used in the local CMS library;
- Classes are still used in the common CMS library and should still use the mainline or varient conventions;
- A class may be used in the local CMS library;

Table 3-1 Environments, Generations and Classes
Environment Type Default Environment CMS Library Mainline or Variant Notes

COMMON APPL Yes

DEVELOPMENT FDEV Yes Mainline Standalone CMS library with no connections to the common CMS library.

DEV Optional Mainline Newer than previous release from which development is occuring. Generally the latest generation.

DEV_TESTING DTST No Mainline Similar to above, except not necessarily the latest generation.

MAINTENANCE MNT Optional Variant Variant from the release from which maintenance is occuring. Generally the latest generation in the variant branch.

MNT_TESTING MTST No Varient Similar to above, except not necessarily the latest variant genaration.

**Table 3-1 Environments, Generations and Classes**
Environment Type	Default Environment	CMS Library	Mainline or Variant	Notes
COMMON	APPL	Yes
DEVELOPMENT	FDEV	Yes	Mainline	Standalone CMS library with no connections to the common CMS library.
	DEV	Optional	Mainline	Newer than previous release from which development is occuring. Generally the latest generation.
DEV_TESTING	DTST	No	Mainline	Similar to above, except not necessarily the latest generation.
MAINTENANCE	MNT	Optional	Variant	Variant from the release from which maintenance is occuring. Generally the latest generation in the variant branch.
MNT_TESTING	MTST	No	Varient	Similar to above, except not necessarily the latest variant genaration.

Access to an application environment always grants access to the class associated with that environment. If SysWorks Administrator is used, access to other classes is read only.

There are two logical names which are used to assist in managing the CMS libraries classes. These are:

appl_CMS_PATH
appl_CMS_VARIANT

Normally these logicals are defined by the application's LOGICALS.COM in the application logical name table.

By supplying combinations of these logical names different effects are produced. Table 3-2 summarises the effects of the combination of these logical names.

Table 3-2 Use of appl_CMS_PATH AND appl_CMS_VARIANT
appl_CMS_PATH appl_CMS_VARIANT Effect

Undefined Undefined No management of classes is performed. BUILDs always use the latest generation of all elements.

Undefined letter Invalid

appl_ envr Undefined Elements are managed within the class. The following behaviour is implemented:

BUILDs use the generations from the class.
CREATE ELEMENT inserts generation 1 of the element into the class.
RESERVE requires the current generation of the element in the class be the latest.
REPLACE inserts the new latest generation of the element into the class.

appl_ envr letter Elements are managed within the class. The following behaviour is implemented:

BUILDs use the generations from the class.
CREATE ELEMENT creates two generations, 1 and 1A1 and inserts generation 1A1 into the class.
RESERVE requires the current generation of the element in the class to be the latest.
REPLACE inserts the new latest generation of the element into the class.

appl_ envr+ Undefined Elements are managed within the class. The following behaviour is implemented:

BUILDs use the latest generations from the class.
CREATE ELEMENT inserts generation 1 of the element into the class.
RESERVE reserves the latest generation of the element within the class.

appl_ envr+ letter Elements are managed within the class. The following behaviour is implemented:

BUILDs use the latest generations from the class.
CREATE ELEMENT creates two generations, 1 and 1A1 and inserts generation 1A1 into the class.
RESERVE reserves the latest generation of the element within the class.

**Table 3-2 Use of *appl*_CMS_PATH AND *appl*_CMS_VARIANT**
appl_CMS_PATH	appl_CMS_VARIANT	Effect
Undefined	Undefined	No management of classes is performed. BUILDs always use the latest generation of all elements.
Undefined	letter	Invalid
appl_ envr	Undefined	Elements are managed within the class. The following behaviour is implemented: BUILDs use the generations from the class. CREATE ELEMENT inserts generation 1 of the element into the class. RESERVE requires the current generation of the element in the class be the latest. REPLACE inserts the new latest generation of the element into the class.
appl_ envr	letter	Elements are managed within the class. The following behaviour is implemented: BUILDs use the generations from the class. CREATE ELEMENT creates two generations, 1 and 1A1 and inserts generation 1A1 into the class. RESERVE requires the current generation of the element in the class to be the latest. REPLACE inserts the new latest generation of the element into the class.
appl_ envr+	Undefined	Elements are managed within the class. The following behaviour is implemented: BUILDs use the latest generations from the class. CREATE ELEMENT inserts generation 1 of the element into the class. RESERVE reserves the latest generation of the element within the class.
appl_ envr+	letter	Elements are managed within the class. The following behaviour is implemented: BUILDs use the latest generations from the class. CREATE ELEMENT creates two generations, 1 and 1A1 and inserts generation 1A1 into the class. RESERVE reserves the latest generation of the element within the class.

During the various version control tasks, generations are duplicated in classes. For example, a TRIAL from development to development testing would cause all the generations in the development class to be inserted into the development testing class.

Contents

Index