Guide to the HP Structure Definition Language

This manual describes the HP Structure Definition Language (HP SDL) and the HP SDL translator.

Revision/Update Information: This revised manual supersedes VAX SDL (Structure Definition Language) Version 3.2.

Operating System and Version: OpenVMS Version 7.2 and higher

Software Version: HP SDL Version 2.3

First Printing, June 1981 Revised, June 1985 Revised, November 1987 Revised, May 1989 Revised, October 2007

Copyright ©1981, 1985, 1987, 1989, 2007

Preface

This manual describes the HP Structure Definition Language (HP SDL) and the HP SDL translator for use on OpenVMS operating systems. HP SDL source code can be translated to output files in one or more target OpenVMS languages. HP SDL is suitable for systems and application programming environments that use executable programs consisting of modules written in one or multiple OpenVMS programming languages.

Intended Audience

This manual is intended for users who are familiar with one or more programming languages and who are currently involved in the design and development of multilanguage programming applications; however, users are not required to have previous experience with HP SDL in order to use this manual.

Document Structure

This manual contains the following chapters and appendixes.

Chapter 1 provides a brief overview of HP SDL and the translation process.

Chapter 2 describes how to create, edit, and process a HP SDL source file using the HP Language-Sensitive Editor (LSE) templates and the SDL command options.

Chapter 3 describes the HP SDL language elements that compose HP SDL declarations.

Chapter 4 describes the function and format of HP SDL declarations.

Appendix A provides a list and descriptions of HP SDL diagnostic messages.

Appendix B shows translation summaries for all output languages supported by HP SDL.

Appendix C is a table showing the ASCII character set.

If HP SDL is installed on your system, an online copy of this manual is contained in SYS$HELP. You can print a copy of the SDL032.LN03 file on a PostScript or .LN03 printer. This file is also contained in the HP SDL kit area, which you can access by contacting your system manager.

Associated Documents

If HP SDL is installed on your system, an online example of a HP SDL source file is contained in EXAMPLE.SDL in the public directory SDL$EXAMPLES.

Conventions

The following conventions are used in this document.

Convention Meaning

{ STRUCTURE }
{ UNION } Stacked items within braces indicate that you must select one of the items.

[ ] Simple square brackets indicate that the enclosed item(s) are optional.

[ COMMON ]
[ GLOBAL ] Stacked items within brackets indicate that only one item may be selected.

MODULE name; Names shown in uppercase letters in examples and format descriptions are HP SDL keywords that must be entered as shown. Names and syntactic elements shown in lowercase letters represent user-specified names and identifiers.

arg,... A comma followed by an ellipsis means that the preceding item may be repeated one or more times, with commas separating two or more items.

.
.
. A vertical ellipsis in an example or figure indicates that not all the statements or elements are shown.

common storage Boldface words in text are used to introduce or define a new term, or to refer to a term used in a code example.

$ LSEDIT USER.SDL In interactive examples, user input is underlined.

Convention	Meaning
{ STRUCTURE } { UNION }	Stacked items within braces indicate that you must select one of the items.
[ ]	Simple square brackets indicate that the enclosed item(s) are optional.
[ COMMON ] [ GLOBAL ]	Stacked items within brackets indicate that only one item may be selected.
MODULE name;	Names shown in uppercase letters in examples and format descriptions are HP SDL keywords that must be entered as shown. Names and syntactic elements shown in lowercase letters represent user-specified names and identifiers.
arg,...	A comma followed by an ellipsis means that the preceding item may be repeated one or more times, with commas separating two or more items.
. . .	A vertical ellipsis in an example or figure indicates that not all the statements or elements are shown.
common storage	Boldface words in text are used to introduce or define a new term, or to refer to a term used in a code example.
$ LSEDIT USER.SDL	In interactive examples, user input is underlined.

Software and Documentation Reporting and Distribution

If HP SDL is installed on your system, an online copy of this manual is contained in SYS$HELP.

The technical changes for this version of HP SDL are described in the online release notes file SDL023.RELEASE_NOTES in SYS$HELP (if HP SDL is installed on your system) and in the HP SDL kit area. You can also access the release notes through the HELP file by typing the following command:

$ TYPE SYS$HELP:SDL023.RELEASE_NOTES [RET]

The following is a summary of technical changes in HP SDL Version 2.3. (For detailed descriptions and a summary of bug fixes, see the online release notes file.)

The BASIC$data-type record definitions generated in BASIC language output have been conditionalized in order to prevent re-definition of these record structures within a BASIC program.
DIMENSION * now yields name[] instead of name[1] in C language output.
In Pascal language output, the [UNSAFE] attribute is now generated for LIST parameters that are conformant strings.
The header that is optionally included at the beginning of an output file now indicates that the file was created by "HP" SDL instead of "VAX" SDL.
The DEFAULT clause may now be specified for a parameter of an AGGREGATE type (i.e. STRUCTURE or UNION).
Macro names generated for ENTRY definitions without an ALIAS clause specified now conform to OpenVMS macro naming conventions. These macro naming changes apply only to BLISS and MACRO language output.
SDL no longer generates CHARACTER*1 in FORTRAN language output for aggregate members of type CHARACTER LENGTH 0. Instead, an informational comment is generated for the aggregate member.
All behavior by the PL/I back end previously under the control of the /VMS_DEVELOPMENT qualifier has now been placed instead under the control of a new qualifier, /PLI_DEVELOPMENT.
The DESCRIPTOR and RTL_STR_DESC parameter passing mechanism attributes are now translated to DESCRIPTOR(S) and DESCRIPTOR(SB), respectively, for ENTRY arguments of type CHARACTER.
The PASCAL back end now coalesces contiguous TYPE and VAR sections under a single incurrence of the keyword.

The following is a summary of new features in HP SDL Version 3.2. (For detailed descriptions, see the online release notes file SDL032.RELEASE_NOTES in SYS$HELP (if HP SDL is installed on your system) and in the HP SDL kit area.)

User-defined data types --- SDL provides the TYPEDEF keyword to allow you to define additional data types in some languages. TYPEDEF behaves like a Storage Class.
Entry point return types --- This feature extends the syntax of the ENTRY statement to allow you to specify a user-defined data type as a return type.
The CONSTANT declaration now includes string constants.
Conditional SDL compilation --- SDL now allows you to compile a section of SDL code conditionally, depending on whether output is being generated for a particular language or not.
Text pass-through --- SDL provides this feature to allow you to pass literal text through to the output language file without translation. This feature allows language-specific constructs that cannot be represented in SDL to be emitted.
DECLARE statement --- SDL provides this statement to allow you to declare a data item of a type that you define, which may be unknown in the current SDL compilation.
READ statement --- SDL provides this statement to allow you to include a .SDI intermediate file in the current compilation, without causing it to be emitted to the output stream.
/SUPPRESS qualifier --- SDL provides this command line qualifier to allow you to suppress the addition of prefixes and/or tags to names.

Chapter 1
Overview

The HP Structure Definition Language (HP SDL) is used to write source statements that describe data structures and that can be translated to source statements in other languages. You can include the resulting output files in a corresponding target language program for subsequent compilation.

Because HP SDL is compiler- and language-independent, it is particularly useful for maintaining multilanguage implementations. For example, you can create and later modify a single HP SDL source file that can be translated to multilanguage output files; any number of these output files can then be included in one or several multilanguage programming applications.

HP SDL supports the following OpenVMS languages:

HP Ada
HP BASIC
HP BLISS
HP C/C++
HP DATATRIEVE
HP OpenVMS DCL
HP FORTRAN
HP MACRO
HP Pascal
Kednos PL/I
SDML
DECTPU
UIL

1.1 The HP SDL Translation Process

The translation of a HP SDL source file occurs when you issue the SDL command (see Section 2.2). The SDL command activates the HP SDL "front-end" translator (SDL$MAIN.EXE), which is stored in the directory SYS$SYSTEM. The front end parses the HP SDL source code and, if you specify the /LANGUAGE qualifier, passes the parse tree to one or more of the HP SDL "back-end" translators. The following table is a list of the back ends that are stored in the directory SYS$SHARE.

Language Back End

HP Ada SDL$ADA.EXE

HP BASIC SDL$BASIC.EXE

HP BLISS SDL$BLISS.EXE

SDL$BLISSF.EXE ¹

HP C/C++ SDL$CC.EXE

HP DATATRIEVE SDL$DTR.EXE

HP OpenVMS DCL SDL$DCL.EXE

HP FORTRAN SDL$FORTRAN.EXE

HP MACRO SDL$MACRO.EXE

HP Pascal SDL$PASCAL.EXE

Kednos PL/I SDL$PLI.EXE

SDML SDL$SDML.EXE

DECTPU SDL$TPU.EXE

UIL SDL$UIL.EXE

Language	Back End
HP Ada	SDL$ADA.EXE
HP BASIC	SDL$BASIC.EXE
HP BLISS	SDL$BLISS.EXE
	SDL$BLISSF.EXE ¹
HP C/C++	SDL$CC.EXE
HP DATATRIEVE	SDL$DTR.EXE
HP OpenVMS DCL	SDL$DCL.EXE
HP FORTRAN	SDL$FORTRAN.EXE
HP MACRO	SDL$MACRO.EXE
HP Pascal	SDL$PASCAL.EXE
Kednos PL/I	SDL$PLI.EXE
SDML	SDL$SDML.EXE
DECTPU	SDL$TPU.EXE
UIL	SDL$UIL.EXE

¹The BLISSF back end generates HP BLISS FIELDSETS for HP SDL aggregates.

Each back end translates only those HP SDL declarations that can (or need) be expressed in that language. HP SDL declarations, described in detail in Chapter 4, translate to the following types of data items:

Scalar or dimensioned scalar data items (ITEM declarations)
Nonscalar data items (AGGREGATE and subaggregate declarations)
Named constants (CONSTANT declarations)
External entries (ENTRY declarations)

Figure 1-1 shows each step in the HP SDL translation process, and the key following the example describes each step. Section 2.2 describes the SDL command in detail.

Figure 1-1 HP SDL Translation Process

Key to Figure 1-1:

The front end (SDL$MAIN.EXE) parses the statements contained in the HP SDL source file TEST.SDL as a result of issuing the SDL command in one of the following four ways:
1. $ SDL/LIST/PARSE/LANGUAGE=BAS TEST.SDL
  If you specify the /LANGUAGE qualifier (for example, /LANGUAGE=BAS), the front end parses the source code and passes the parse tree to the back end for the specified language (for example, SDL$BASIC.EXE). (The function of the /LIST qualifier is described at the end of step 1. The /PARSE qualifier is shown here for completeness, but it is the default for this command and does not need to be specified.)
2. $ SDL/PARSE=TEST/LIST TEST.SDL
  If you do not specify the /LANGUAGE qualifier, but specify instead the /PARSE qualifier and an output file name, the front end parses the source code and writes the parse tree to an intermediate file with a default file type of .SDI.
3. $ SDL/PARSE=TEST/LIST/LANGUAGE=BAS TEST.SDL
  If you specify the /PARSE qualifier with an output file name and the /LANGUAGE qualifier, the front end parses the source code, writes the parse tree to the specified intermediate file (for example, TEST), and passes the parse tree to the specified back end.
4. $ SDL/PARSE/LIST TEST.SDL
  If you specify the SDL command with the optional /PARSE and /LIST qualifiers and do not specify an intermediate file name, the front end parses the source code (checking for errors), but does not generate an intermediate file.
The front end produces a .LIS file as a result of specifying the /LIST qualifier on all the SDL commands described in steps 1a. through 1d. The .LIS file contains a line-numbered copy of your source code and describes any errors or warnings encountered during the translation process.
If you specify the /PARSE qualifier and an output file name, as in step 1b. or step 1c., you may later decide to translate the intermediate (already parsed) code to one or more language output files (for example, TEST.BAS) by entering the following command:
$ SDL/NOPARSE/LANGUAGE=BAS TEST.SDI

Note
In cases where HP SDL translation must be performed at a customer site, the intermediate .SDI file is included in the software HP sends to customers.
If you enter the command in step 2, the alternate front end (SDL$NPARSE.EXE) passes the parse tree (in TEST.SDI) to the specified back end (SDL$BASIC.EXE).
The specified back end (SDL$BASIC.EXE) produces an output file with the default file type of .BAS.

You can specify any or all of the language options on the /LANGUAGE qualifier, and HP SDL produces separate output files for each language specified.

1.2 Description of a Sample HP SDL Source File

Example 1-1 is a typical HP SDL source file, and the key following the example describes each of the numbered language elements. (Chapter 3 describes all the language elements in detail.) You may want to familiarize yourself with this example because it shows the source file you will be creating in the LSE tutorial in Section 2.1.2.

Example 1-1 Sample HP SDL Source File

MODULE opr_descriptor IDENT "Version 2.0";(1) /* define constants and node structure for operators;(2) #max_args = 10;(3) CONSTANT (fixed_binary,floating,char,untyped) EQUALS 1 INCREMENT 1;(4) AGGREGATE operator STRUCTURE(5) PREFIX "opr_";(6) flink ADDRESS;(7) blink ADDRESS; opcount WORD; optype CHARACTER LENGTH 1; id WORD; operands LONGWORD DIMENSION 0:#max_args-1;(8) END operator; #opsize = .;(9) CONSTANT opr_node_size EQUALS #opsize / 2; ITEM current_node_ptr(10) ADDRESS(11) GLOBAL;(12) END_MODULE opr_descriptor;(13)

Key to Example 1-1:

All HP SDL declarations are grouped within modules, and you must assign a name to each module. The IDENT keyword precedes any commented information that you may want to add to describe the MODULE declaration.
Output comments begin with a slash and an asterisk (/*) and are written to the language output file unless the /NOCOMMENTS qualifier is specified.
Local symbols begin with a pound sign (#) and are not written to the output file. Local symbols may be used to express values in declarations. For example, the symbol #max_args is used in the declaration of the array operands.
CONSTANT declarations produce declarations of named constants. When the INCREMENT option and an increment value are specified, HP SDL automatically increments the initial value for each of the declared output constants. In the example, fixed_binary will be assigned the value 1, floating will be assigned the value 2, and so on.
AGGREGATE declarations define data structures and their members.
When the PREFIX option and a prefix are specified, HP SDL concatenates the prefix and a data type code to the declared aggregate member names in the language output files. Compare these aggregate member name declarations with the Kednos PL/I output shown in Example 1-2.
Aggregate members are declared using reserved HP SDL data type keywords.
An aggregate member or a scalar data item can be declared to be an array by specifying the DIMENSION option. In this example, the array operands has 10 elements, with subscripts 0 through 9.
The period (.) represents the current byte offset within an AGGREGATE declaration. The local symbol assignment #opsize = .; captures the size of the constant portion of the structure operator. The value of this local symbol is then used in the declaration of the constant opr_node_size.
ITEM declarations, such as the declaration of current_node_ptr, define scalar data items.
The ADDRESS keyword specifies a data type that is an address, or pointer.
The GLOBAL keyword specifies global storage to override the default language storage class for an ITEM or an AGGREGATE declaration.
The END_MODULE keyword ends a MODULE declaration; you may optionally specify the MODULE name after the END_MODULE keyword.

Example 1-2 shows the Kednos PL/I output file that results from translation of the HP SDL source file shown in Example 1-1.

Example 1-2 Kednos PL/I Output File for the Sample HP SDL Source File

/************************************************************************** /* Created 17-AUG-2007 11:23:49 by OpenVMS SDL EV2-3 Source: 13-AUG-2007 08:37:41 FOO$:[DIR]TEST.SDL /************************************************************************** /*** MODULE opr_descriptor IDENT Version 2.0 ***/ /* define constants and node structure for operators; */ %replace fixed_binary by 1; %replace floating by 2; %replace char by 3; %replace untyped by 4; %replace opr_s_operator by 53; dcl 1 operator based, 2 opr_a_flink pointer, 2 opr_a_blink pointer, 2 opr_w_opcount fixed binary(15), 2 opr_t_optype character(1), 2 opr_w_id fixed binary(15), 2 opr_l_operands (0:9) fixed binary(31); %replace opr_node_size by 26; dcl current_node_ptr pointer globalref;

Chapter 3 describes all the HP SDL language elements, and Chapter 4 describes the function and format of each of the HP SDL declarations.

Contents

Index