28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #1
ERICSSON /// DOCUMENT INSTRUCTION
Uppgjord - Prepared Faktaansvarig - Subject Nr - No
ETX/TX/DZ GURE responsible 1/1013-FCK 114 22
IXG/DM/DT EKON Uen
Dokansv/Godk - Doc Kontr - Checked Datum - Date Rev File
respons/Approved 1996-01-01 D
ETX/TX/DT (H. Westlund)
SOURCE PROGRAM INFORMATION FOR PLEX CP
SOFTWARE UNITS
Contents
1 REVISION INFORMATION
2 APPLICATION
3 PURPOSE OF THIS DOCUMENT INSTRUCTION (DI)
4 SOURCE PROGRAM INFORMATION FOR PLEX CP SOFTWARE UNITS
(SPI)
4.1 Purpose of an SPI for PLEX CP Software Units
4.2 Users of an SPI for PLEX CP Software Units
4.3 Identification of an SPI for PLEX CP Software Units
4.4 Contents of an SPI for PLEX CP Software Units
4.5 Writing an SPI for PLEX CP Software Units
5 GLOSSARY
6 REFERENCES
1 REVISION INFORMATION
This is a new document, which replaces the following document:
Document Instruction for Source Program Information for CP Software Units; TX/DZ-91:109 Uen.
The following changes have been made:
Minor corrections
Document title changed
C
Minor updates done according to PSG FMp4 review meeting.
2 APPLICATION
This document instruction should primarily be used for preparing Source Program Information for PLEX CP
Software Unit documents within the AXE 10 software design.
3 PURPOSE OF THIS DOCUMENT INSTRUCTION (DI)
This DI defines the structure and contents of the Source Program Information for PLEX CP Software Units.
4 SOURCE PROGRAM INFORMATION FOR PLEX CP SOFTWARE UNITS
(SPI)
4.1 Purpose of an SPI for PLEX CP Software Units
The purpose of the Source Program Information for PLEX CP Software Units is to define the implementation
of the functions of a CP software unit in AXE using the PLEX-C programming language.
The Source Program Information for PLEX CP Software Units is used as a unit description for the designer for
program design and modification and as a source document for APS production.
4.2 Users of an SPI for PLEX CP Software Units
Those who need information and guidelines from the Source Program Information for PLEX CP Software
Units are:
Designers
Testers
Customers
4.3 Identification of an SPI for PLEX CP Software Units
The document is identified in the id-sector and is to contain the following information:
SYNTAX EXAMPLE
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #2
ID
ID UPROGRAM TYPE DOC; ITUPROGRAM
TYPE DOC;
UPROGRAM is the APS document name of the source program information,
where is the function designation of the source software unit. A 'U' after the
block name indicates a PLEX CP SW unit.
CLA 190 55; CLA 190 55;
NUM CAA 107
NUM CAA ;
1699;
REV; REV A;
Z is the revision state of the document. Letters I, O, P, Q, R, U, W and symbols,
for example # and @, must NOT be used.
DAT ; DAT 83-07-15;
DES XT/ROG
DES ;
IHS;
RES
RES ;
XT/ROGC;
APP
APP ;
XT/ROGC;
END ID; END ID;
Only the first three characters of a string are necessary to type. However, the compiler reads all the
characters of the string; therefore, everything must be correctly written.
4.4 Contents of an SPI for PLEX CP Software Units
All Source Program Information documents are to have a uniform structure and layout. This is obtained by
using the Source Program Information skeleton in the project methods library or the PLEX skeleton generator
in APS tools.
The Source Program Information has the following contents:
1
GENERAL
2
DECLARE
2.1
GLOBAL SYMBOLS
2.2
LOCAL SYMBOLS
2.3
RECORDS AND FILESIZES
2.4
COMMON STORED VARIABLES
2.5
TEMPORARY VARIABLES
2.6
STRUCTURES
2.7
STATES AND SYMBOLS
3
PROGRAM
3.1
MULTI-FUNCTION SIGNAL ENTRIES
3.2
STANDARD SUBPROGRAMS IN PLEX
3.3
APPLICATION SUBPROGRAMS IN PLEX
3.4
APPLICATION SUBPROGRAMS IN ASA
3.5
SUBROUTINES IN PLEX
3.6
SUBROUTINES IN ASA
4
DATA
4.1
SIZES
4.2
INITIAL DATA
4.3
ALLOCATIONS
5
LOCAL SIGNALS
4.5 Writing an SPI for PLEX CP Software Units
This section explains how to write a Source Program Information document for CP Software Units. It defines
the headings and numbering to be used. Under each heading there is an explanation of what the specific
heading is to comprise.
4.5.1 1 GENERAL
This chapter is to contain a short description of the implemented functions of the software unit and a history of
the changes made to the document. Any abbreviations used are also to be listed here.
4.5.2 2 DECLARE
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #3
This chapter is to contain the DECLARE sector, in which all data units are declared.
4.5.2.1 General Rules
The program's DECLARE sector is written under the heading "DECLARE". The function of the sector is to
declare the data units, for example, variables and symbols with descriptive comments.
Units of the same type are written in alphabetical order under their subheading.
Each element is to be declared with a keyword and name in one statement, and a comment. Possible length
and property (even default values) are to be stated.
Example:
VARIABLE DEVADDR 16 DS RELOAD; !RP-CM ADDRESS INFORMATION!
VARIABLE DIGIT 8 CLEAR; !1ST B-NO DIGIT!
Variables required for macros and procedures are to be commented with the text "USED IN MACRO" and
"USED IN PROCEDURE".
4.5.2.2 Naming Rules
Functional names are to be chosen for number symbols, variables, subvariables and pointers. A functional
name of a variable is a name that helps the reader of the program to understand what data the variable
contains. The names are to be as specific as possible. If possible, abbreviations for concepts which are
seldom used are to be avoided. If abbreviations do occur, these are to be explained in the "GENERAL"
chapter of the Document Instruction.
When reading a program, you may quickly want to see if a variable is temporary or stored. This must,
therefore, be apparent from the name. In the following chapters, a number of rules are stated for naming
variables.
Naming of Variables in Records
A symbol variable for a state is to be called STATE. If an extra symbol variable is needed for signal
branching, it is to be called BRANCHSTATE. A symbol variable for return from a subroutine called with GOTO
is to be named "RETURN + subroutine name".
Naming of Stored Variables Outside Records
The name is to be "C + functional name", for example, CIOCODE, COWNREF, CCHANNELNUMBER. If the
variable is used for storage of a pointer value, the name is to be "C + pointer name", for example, CDEVP.
A symbol variable for state is to be called CSTATE. If an extra symbol variable is required for signal
branching, it is to be called CBRANCHSTATE. A symbol variable for return from a subroutine which is called
with GOTO is to be named "CRETURN + subroutine name".
Naming of Temporary Variables
The name is to be "T + functional name", for example, TSTARTPHASE, TBLOCKSIZE. Names of type TEMP
are not permitted. If the variable is to be used for storing a pointer value, the name is to be "T + pointer name",
for example, TDEVP. A variable named TPLUS is used for receiving irrelevant data in signals.
Naming of Pointers
The name of a pointer is to be functional and it is to end with -P, -PTR or -POINTER.
Naming of Subvariables
Functional names are to be used.
Naming of States
Functional names are to be used.
Naming of Program Labels
Program labels are given names to make them easy to find. The labels are to have names consisting of the
subprogram designation (an easily pronounceable abbreviation of the subprogram name), followed by a
consecutive number, for example, BLOCKSPV10.
The consecutive number is incremented within every subprogram or program. The incrementing is performed
in steps of 10 in order to allow insertion of new labels.
There can be certain functional label names in a program. These can be used as jump addresses in error
situations and exits, for example, FORMATERROR, EXIT.
Naming of Subroutines
Functional names are to be used.
Naming of Symbol Values
The symbol values used in symbol variables are to have functional names. However, the following special
rule applies: The symbol values used in the symbol variables BRANCHSTATE and CBRANCHSTATE for
signal branching are given the same name as the name of that program label to which a jump is to be made.
Naming of Number and String Symbols
Functional names are to be used. Names ending with -P, -PTR and -POINTER are to be avoided.
Furthermore, there are design rules for:
Restart Phases
Block types
Size alteration events
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #4
IO codes
These are applicable through a Design Rule tool.
4.5.2.3 2.1 GLOBAL SYMBOLS
All global number symbols and global strings are written under this heading. Global symbols are used when
market-dependent values (numeric or alphanumeric) are required and for system-defined values.
Examples of values which can be specified as global number symbols and strings are:
Block types
Command names
Command and printout categories
Keywords are GLOBAL NSYMB and GLOBAL STRING.
4.5.2.4 2.2 LOCAL SYMBOLS
All local number symbols are written under this heading. Local number symbols begin normally with Z and
are used when value assignment can be performed by the designer.
Examples of values which can be specified as local symbols are:
Restart phases
Size alteration events, for example, SIZEALT
Error codes, for example, ZERRORCODE
Keyword is NSYMB.
4.5.2.5 2.3 RECORDS AND FILESIZES
All declarations of records, pointers and filesizes are written under this heading.
The keywords RECORD and END RECORD are written on separate lines.
The same rules apply to the record variable declarations as to the common stored variables.
Directly after END RECORD the pointer is to be declared on a new line with the keyword POINTER.
The chapter is terminated with FILESIZE statements, if any.
4.5.2.6 2.4 COMMON STORED VARIABLES
Stored variables not included in a record are declared under this heading.
For variables containing error codes, all error codes are to be specified in symbolic form in the comment. The
numeric value is specified in the chapter "Local Symbols".
Note that the states of the symbol variables are described in the chapter "STATES AND SYMBOLS".
If a variable consists of subvariables, then "See Structure" is also written in the comment.
4.5.2.7 2.5 TEMPORARY VARIABLES
All temporary variables are declared under this heading.
4.5.2.8 2.6 STRUCTURES
All the structure declarations are gathered under this heading. Structuring of a variable is made if the length
exceeds 16 bits or the variable parts are to be used in program sectors.
The comment from the main variable declaration is to be repeated in the structure declaration.
The declaration is formatted in such a way that the level division becomes visible. This is best done by
placing the levels in different tabulating positions.
Subvariables are always to be given with full qualification in the program sector.
Example: CDIGITS.ADIG
4.5.2.9 2.7 STATES AND SYMBOLS
In this chapter all the states and symbol values that the program's symbol variables can assume are
described in the form of a comment. The states/symbols are grouped per symbol variable, with the variable
name as a heading. The variables are written in alphabetical order like the states/symbols per variable. Each
state/symbol is described on one line.
When using ordinary field variables for storing states/symbols, then these states/symbols are also described
in this chapter.
4.5.3 3 PROGRAM
This chapter is to contain the PROGRAM sector(s) where the program logic is written.
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #5
4.5.3.1 General Rules
Under the heading PROGRAM, the program logic is divided into subprograms implementing the functions
described in the block description
Subprograms are not to be too large. If the subprogram is complex, it is especially important that it is not
large. As a rule of thumb, 50 to 100 statements are a suitable size for a subprogram.
By means of heading comments, each subprogram or subroutine is to be described in a header.
If the subprograms are subdivided further, then each part is described in the same manner. Furthermore, the
readability can be improved by including comments within the code.
RECEIVE statements in assembler programs are to have all signal data as a statement comment.
!
>WRTDEV>
!
RECEIVE WRTDEV WITH
DEVP, ! PR0 + DEVP
CSENDBLOCK, ! DR0 = SENDING BLOCK
!
CSENDIND; ! DRI = SENDINGINDIVIDUAL !
4.5.3.2 Interwork between Subprograms
Jumps between subprograms are permitted only in special cases, for example to certain labels in error
situations, such as FORMAT ERROR and UNREASONABLE VALUE, and when receiving commands.
Furthermore, the EXIT label is to be found in the program. Its only statement is an EXIT statement. This label
is the last label before the subroutines and can be utilized in BRANCH and IF statements for exiting.
If several subprograms need the same code sequence, then it is to be placed as a subroutine.
Interwork between subprograms in different sectors can be implemented by sector signals (TRA and ENT
statements).
4.5.3.3 Number Symbols
Numeric constants are always to be implemented by number symbols. Number symbols are also to be used
for other constants as a simple way of increasing program readability.
Example:
CALLCNT = ZRESET;
says much more than
CALLCNT = 1000;
even if ZRESET always means 1000.
On the other hand, number symbols without a functional name, for example, NINETYSEVEN, are unsuitable.
4.5.3.4 Double Utilization
Variables are not to be doubly utilized. The use of a variable is to agree with its name and its purpose.
Program labels are not to be doubly utilized either. For example, if a selection structure is terminated with a
program label and followed by an iteration which begins with a program label, then it is unsuitable to use the
same label for both of the structures. Two labels are to be placed close to each other, so that it will be easy,
when needed, to insert statements between the selection and the iteration.
4.5.3.5 Subroutines
Common blocks of code used by different subprograms within the program should be implemented as a
subroutine.
4.5.3.6 Macro Calls
If the code has been produced through a macro expansion and has not been altered, then the macro call is
to be inserted as a heading comment (without semicolon) prior to the expanded code.
4.5.3.7 Operators
Operators, for example +, -, (+), <= and = (the equality sign), are to be surrounded by blanks to improve the
readability.
4.5.3.8 Commands and Printouts
There are design rules applicable through a design rule tool for command and printout programs for, among
others, program division.
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #6
4.5.3.9 Contents in Program
The contents are divided into:
Signal reception for multi-function signals (see below under MULTI-FUNCTION SIGNAL ENTRIES)
Subprograms are grouped under the following headings:
STANDARD SUBPROGRAMS IN PLEX
APPLICATION SUBPROGRAMS IN PLEX
SUBPROGRAMS IN ASA
Subroutines are grouped under the following headings:
SUBROUTINES IN PLEX
SUBROUTINES IN ASA
The headings are mentioned in the order they are to be placed in the chapter PROGRAM.
The subdivision in PLEX and ASA is only significant if both types exist.
4.5.3.10 3.1 MULTI-FUNCTION SIGNAL ENTRIES
Heading: MULTI-FUNCTION SIGNAL ENTRIES
These are the entries for the signals which require a branching before appropriate actions can be performed.
Signals not requiring branching can be identified under the above heading as well in order to facilitate the
search for program entries.
Directly after the reception statement, a jump occurs to the correct subprogram depending on the state. The
subprogram name from the list of contents is given as a comment. In the subprogram, in the destination of the
jump, the signal reception is identified in the normal way. When required, a special symbol variable named
BRANCHSTATE or CBRANCHSTATE is created to be used at signal branching. The same name is used for
the symbol name as the program label to which the jump is made.
Example:
ENTER SIGNAL WITH ...!
BRANCH ON CBRANCHSTATE
TO LASUP10 IF LASUP10 ! SEE SUBPROGRAM: !
TO CMMAIN20 IF CMMAIN20 ! SEE SUBPROGRAM: !
ELSE TO EXIT;
4.5.3.11 3.2 STANDARD SUBPROGRAMS IN PLEX
Heading: STANDARD SUBPROGRAMS IN PLEX
For example the following subprograms belong there:
START/RESTART
SIZE ALTERATION (optional)
DATA BACK UP (optional)
CM MAINTENANCE (optional)
TIME SUPERVISION MODULE (optional)
3.2.1 START/RESTART
The program restart functions are written here. If the functions are divided into several start phases, a
corresponding division of the program is made.
3.2.2 SIZE ALTERATION
Under this heading, the program code for increasing and decreasing size-alterable data files sizes is found.
This code is normally generated by means of a macro.
3.2.3 DATA BACK UP
This heading is found only in programs that need to be informed when the output of a large or small dump of
the data store is to be performed, or in programs that have variables which are included in the small data
dump.
Such programs have a special block type. The blocks that need information when dumping starts and
terminates can then prevent writing in RELOAD variables during dumping.
Blocks which have variables for the small data dump are to communicate this in a backward signal to the
operating system as an answer to a combined signal. The code for this is generated with a macro.
3.2.4 CM MAINTENANCE
Under this heading, the CM-holding blocks are to have functions for maintenance of CM and EM.
Examples of such functions are: Local restart of CM, insertion of EM, blocking/deblocking of EM.
3.2.5 TIME SUPERVISION MODULE
Under this heading, the subprograms for common time supervision are found.
4.5.3.12 3.3 APPLICATION SUBPROGRAMS IN PLEX
Heading: APPLICATION SUBPROGRAMS IN PLEX
This is a summarizing heading for the subprograms written in PLEX that are unique to the unit. These
subprograms, which normally form the main part of the code, are thus not of a standard nature. The
subprograms under the heading are to correspond to the functions/subfunctions which are found in the
28/02/2005 http://garbowww.ericsson.se:80/tomax/mdocs/001-01013-022_D/mdoc.html #7
Function Description and the Block Description. The subprogram names are to be taken from there.
4.5.3.13 3.4 APPLICATION SUBPROGRAMS IN ASA
Heading: APPLICATION SUBPROGRAMS IN ASSEMBLER
This is a summarizing heading for the subprograms written in assembler that are unique to the unit. Possible
subroutines, which are called from the subprograms, are placed last under this heading.
4.5.3.14 3.5 SUBROUTINES IN PLEX
Heading: SUBROUTINES IN PLEX
All PLEX subroutines are placed in alphabetical order under this heading. Each subroutine forms a
subchapter with the subroutine name as a heading.
4.5.3.15 3.6 SUBROUTINES IN ASA
Heading: SUBROUTINES IN ASSEMBLER
Subroutines written in Assembler are gathered under this heading. Each sector is commented on in the same
way as a PLEX subroutine.
4.5.4 4 DATA
This chapter contains the DATA sector, in which the record sizes and initial data are declared.
4.5.4.1 4.1 SIZES
Fixed file sizes and initial file sizes for size-alterable files are indicated under this heading.
4.5.4.2 4.2 INITIAL DATA
All values of variables that are needed for the initial start of the exchange are specified under this heading.
4.5.4.3 4.3 ALLOCATIONS
Allocation of base addresses is done under this heading.
4.5.5 5 LOCAL SIGNALS
This chapter is not mandatory, it is only written for local signals.
The local signals used in this Source Program Information are described here.
Using the same format as in ordinary signal descriptions.
5 GLOSSARY
CP
Central Processor
SPI
Source Program Information
6 REFERENCES
Name Number Stored
Software Reliability Handbook EN/LZG 205 603 -