5. CA MICS/SAS Coding Conventions › 5.2 CA MICS Coding
5.2 CA MICS Coding
CA MICS has been designed and implemented to perform a wide
range of functions. However, CA MICS also recognizes the
need for limited user modification of the standard product to
accommodate unusual circumstances.
Almost all of the logic of CA MICS is programmed in SAS.
Most of the modifications you make will be in SAS.
There are other languages involved in CA MICS. Some
assembler code is involved, notably in the CA MICS IMS
Analyzer. CA ISPF Dialog Assist and ISPF panel definition
logic are used in the CA MICS Workstation Facility (MWF).
CA MICS installation and operational JCL are coded in a
suitable CA Incorporated language called GCL (Generation
Control Language). CA MICS products are generated from a
kind of language called Component Generator Definition
Statements.
The principles of each of these languages are given in other
sections of this document.
Guidelines for coding CA MICS modifications within the
framework of CA MICS design targets in the most efficient
manner are described below.
Maintainability Standards
Maintainability standards established for CA MICS include
tracking user modifications, using comments in code,
parameter library coding, and pointers for coding CA MICS
exits using SAS. Each topic will be addressed in turn.
One of the most important aspects of making user
modifications to CA MICS is the ability to track the actual
changes. Such tracking is necessary to:
- verify the logic added in case of questionable results
- determine the impact of vendor-supplied product
maintenance on the change
- develop a plan for merging modified data with
unmodified data for long-term reporting
The CA MICS System Administrator Guide is the central place
for coordinating product maintenance. This document contains
a section called User Modification Descriptions. Use this
section to log ALL user modifications at the earliest
possible time. In the event CA MICS product support is
needed at your site, an accurate and timely record of
user-applied changes can greatly simplify problem
determination and correction.
The User Modification section of the System Administrator
Guide is organized in two parts: an index to the changes and
a summary description of each change.
The index is a list of user modifications. The index has
columns for a change number (user-assigned), date of the last
entry for the change, status of the change, whether the
change has been superseded by another modification, and other
notes that apply to the change.
Creative use of the status column of the index provides a
vehicle for entering changes into the System Administrator
Guide even before they are implemented. Such logging would
help identify possible change interference situations
earlier.
The User Modification Description forms in this section
provide a handy method for recording the INTENT as well as
the logic and implementation of a change.
The content of each information category of the User
Modification Description log sheet is free-form. However,
the contents of each section typically contain the following:
Log Topic Typical Contents
------------------------- --------------------------------
MODIFICATION TITLE: A one-line title describing the
intent of the modification.
MODIFICATION NUMBER: A user-assigned number, such as
UMOD-001, indicating a user
modification to CA MICS, number
1 in a series.
MODIFICATION AUTHOR: Your name.
MODIFICATION DATE: Implementation date.
MODIFICATION DESCRIPTION: A meaningful description of the
intent and implementation method
of the change. Any data that is
possibly pertinent should be
included, such as whether the
change has a fixed useful life
and should be removed at a later
date.
REASON FOR MODIFICATION: A SHORT history of the need for
the change, including such items
as requestor ID, date the need
was identified, reference to
other existing code that uses
the method, and reference to the
method's source.
CA MICS MODULES MODIFIED: List all CA MICS modules
modified by the change, and the
libraries on which they reside.
MODIFICATION SOURCE: The location of the IEBUPDTE
stream that applied the change.
Comments
The considerations described for coding comments in SAS code
(Section 5.1 of this guide) also apply to coding comments in
CA MICS code.
Additional guidelines for commenting CA MICS code are:
- Include a comment for each change showing the date of
the change, the purpose of the change, and the person
who coded the change.
- Log the change in the User Modification section of the
CA MICS System Administrator Guide. Accurate and
timely logging of these changes is absolutely necessary
to assure your ability to install normal vendor
maintenance.
The format of comments changes, according to the language
being used. Code comments in the format that applies only to
the language you are modifying.
- SAS comment formats are described in the previous
section.
- Assembler language recognizes comments on a code line
as following the operands. Comment lines can be coded
by putting an asterisk (*) in column 1 of an assembler
statement.
- All CA MICS parameter library members that do not
contain JCL or prototype JCL have an asterisk comment
facility. If the first non-blank character on any
record in the PARMS library member is an asterisk (*),
the line is treated as a comment. The asterisk must be
the first non-blank character on the line, but does not
have to be in column one of the line.
- PROTOLIB members and members of the PARMS library that
contain JCL may contain comments at two levels. Code
comments that you want to show in the generated JCL
with "//@" beginning in column 1 of the line. Code
comments that you want in the member but NOT in the
generated JCL with ":*" beginning in column 1 of the
line. For example,
+---------------------------------------------+
| |
|:* THIS COMMENT WILL NOT APPEAR IN |
|:* GENERATED JCL |
|//@ COMMENT FOR JCL |
|//INPUTSMF DD ...etc |
| |
+---------------------------------------------+
- Code comments in CLIST code and MICF panel code with
"/*" as the first and second non-blank characters in
any line, and not necessarily in column 1 of the line.
- Code comments in MICF dialog skeletons with ")CM "
beginning in column 1 (i.e., a right parenthesis in
column 1, the letters CM in columns 2 and 3, and a
BLANK SPACE in column 4).
CA MICS Parameter Library Member Coding
The prefix.MICS.PARMS library and the sharedprefix.MICS.PARMS
library contain a number of members which specify the options
to control various parts of the total CA MICS system.
Members either contain control statements or are exit
routines coded in SAS.
The format of control statements is free-form but
positional. This means that any number of blanks many come
before and after any variable in a parameter member, but all
variables must be specified and specified in the order shown.
There is no explicit provision for the continuation of
control cards. Our approach has been to allow the repetition
of control cards when more variables must be specified than
can fit on a single card. Comments are supported in all of
the PARMS library members. If the first "variable" is "*",
the card is ignored. For those parameter statements that
begin with a keyword, the keyword MAY NOT BE ABBREVIATED--it
must be coded exactly as shown in the documentation.
CA MICS SAS Coding
In writing SAS code for use with CA MICS, remember the
following guidelines:
- Validate the fields your exits use to make processing
decisions. While CA MICS does some basic validation,
it cannot catch the kinds of installation specific
errors you can (such as an invalid account number on a
JOB card).
When one of your exits detects invalid input data, it
should not pass it into the database because doing so
increases the size of the database and decreases its
usefulness for analysis and reporting.
Rather, your exits should take a default action when
they detect invalid input data. For example, you could
assign a job with an invalid account code to an
overhead category.
- Test your exit code. Exit code is inserted directly
into CA MICS processing logic, so you should ensure
that this inserted code will cause subsequent CA MICS
logic to operate abnormally. Observing the following
DOs and DON'Ts should assure proper implementation of
exits:
**** D O the following: ****
DO: Use the member supplied in the distributed version of
the CA MICS.PARMS library as the starting point for
your exit, where appropriate.
DO: Liberally comment all code.
DO: Examine input record length to be sure INPUT requests
can be satisfied from the current record.
DO: Refer to input field locations with pointer logic
where possible.
DO: Preserve data element integrity by type (numeric,
time stamp, character variable) and range (having the
value agree with the FORMAT and LENGTH specs).
DO: Define new retained data elements by specifying the
RETAIN statement after LENGTH and FORMAT statements,
if applicable.
DO: Test all exit logic under the CA MICS-required SAS
release.
DO: Call CA Technical Support if you have ANY questions.
DO: Code percent sign constants as double %% if such
constants are necessary in code that appears in a
CA MICS SAS Macro statement.
**** D O N ' T do the following: ****
DON'T: Reset SAS compilation options by using the SAS
OPTIONS statement without examining the impact of
such a change on the rest of CA MICS logic.
DON'T: Use columns 73-80 for SAS statements. CA MICS only
uses 1-72.
DON'T: Code these SAS statements in your exit: RETURN,
DELETE, or INPUT without a trailing "@".
DON'T: Code INPUT statements that could cause SAS to
perform an automatic input statement skip. Use
the RECLEN variable to be sure the record is big
enough to contain data at any intended input
offset.
DON'T: Forget the CA MICS naming standards, especially
for DDnames, file names, and data element file
prefixes.
DON'T: Assume that any data element is RETAINed or not
RETAINed.
DON'T: Redefine any currently-existing CA MICS data
element unless the documentation of the specific
exit in question says it is allowed.
DON'T: Assume that the SAS automatic variable _N_
contains the actual input observation number.
DON'T: Assume that setting the SAS automatic variable
_ERROR_ will cause an input observation to be
ignored or CA MICS processing to terminate.
DON'T: Use SAS language features not supported by the SAS
release specified for use by the CA MICS update
process.
