The following list briefly describes the process required to write
a new SCLM language definition:
- Define the language name to SCLM.
- Define include-sets for the language to identify the locations
of included members.
- List the various programs (parsers, compilers, and so on) used
to parse and build your source.
- For each program (or translator), look up the ddname substitution
list (usually in the Programmer's Guide for the compiler), or list
the ddnames used by the program.
- For each program or translator, write an FLMTRNSL macro followed
by FLMALLOC macros (one for each ddname to be allocated for the translator).
Use the information in the program documentation to determine which
IOTYPE value to specify as well as which other FLMALLOC keywords are
appropriate.
- Write a sample architecture definition and send it to your users.
Describe to your users how to convert a JCL file of linkage editor
control statements into architecture definitions.
- Place the application under SCLM control.
This section is an illustration of the process for defining a language
to SCLM. As you progress through the definition, you will code SCLM
macros with the information SCLM needs to control Finnoga 4 modules.
You will place this code into a member of the PROJDEFS.SOURCE data
set called @FINNOGA. Language definitions such as @FINNOGA are usually
referenced in the code for a project definition by means of the COPY
statement.
- Step 1.
- Define the language.
The first step is to tell SCLM that you
are defining a new language. To do so, code the following FLMLANGL
macro:
FLMLANGL LANG=FINNOGA,VERSION=FINN4
In
this example, values are specified for two parameters. The default
values are used for the other parameters.
- Parameter
- Description
- LANG=
- Specifies the language name a user must enter on the SPROF panel
or on the Migrate Utility panel to request that this language definition
be used to drive build and parse operations of the Finnoga 4 modules.
- VERSION=
- Identifies the specific release of the current Finnoga 4 compiler.
If you install a new release or version of the Finnoga 4 compiler,
you can set this parameter to a different value so that SCLM can mark
all Finnoga 4 modules needing to be rebuilt. You must then re-assemble
and link your project definition.
- Step 2.
- Define include sets
for the language to identify the locations of included members.
After
the language is defined, you can specify where SCLM finds included
members for the Finnoga 4 language. In the following example, the
FLMINCLS macro
is used to list the types that are searched for includes:
FLMINCLS TYPES=(INCLUDE,@@FLMTYP)
In
this example, the TYPES parameter of the
FLMINCLS macro
is used to tell SCLM where to look for includes. Because no name is
specified, this definition applies to the default
include set.
- Parameter
- Description
- FLMINCLS name
- Specifies the name of the include set that
uses this definition. If no name is specified (as in this example),
the definition is associated with the default include set. An include set defines
a search path for all includes associated with that include set. Multiple include set s
can be specified in a language definition if the parser and compiler
support distinguishing one kind of include from another. For the parser,
this means that the syntax of the language must support determining
which include set an
include belongs to. For the compiler, this means that a separate ddname
must be used for each different include set (kind
of include).
Two include sets are
useful when the standard language includes are kept in one Type and
the “EXEC SQL” includes are kept in another Type. A parser can be
written to determine which include set each
include is in. The language definition then associates a ddname from
the build translators with the appropriate include set name.
- TYPES=
- Specifies the name(s) of the types which are searched to find
includes. In this case, the “INCLUDE” type is searched first. The
@@FLMTYP SCLM variable indicates that the type of the member that
is processed by the Finnoga 4 compiler is to be searched next. For
example, if 'EXAMPLE.USERX.SOURCE(PROGA)' is going to be compiled,
SCLM looks for includes first in the data sets associated with the
INCLUDE type and then the SOURCE type.
- Step 3.
- Specify the programs that process the modules.
Next, identify
the programs that are used to parse and build the Finnoga 4 modules.
There are usually two such programs: a parser and the compiler. For
each of these programs, code an FLMTRNSL macro and the appropriate
FLMALLOC macros and FLMCPYLB macros.
Assume that you have
written your own parser and that it is in the data set SCLM.PROJDEFS.LOAD(FINPARSE).
The parser requires an option string @@FLMSIZ,@@FLMSTP,@@FLMLIS, and
reads the source from ddname SOURCE.
Add this to your language
definition:
FLMTRNSL CALLNAM='FINNOGA PARSER', C
FUNCTN=PARSE, C
COMPILE=FINPARSE, C
DSNAME=SCLM.PROJDEFS.LOAD, C
PORDER=1, C
OPTIONS=(@@FLMSIZ,@@FLMSTP,@@FLMLIS)
The parameters included in this example are described as follows:
- Parameter
- Description
- CALLNAM=
- A character string that appears in messages during the specified
FUNCTN (in this case PARSE). This value will assist in recognizing
which translator was executing during the specified FUNCTN.
- FUNCTN=
- The value PARSE tells SCLM that this program is to be invoked
whenever you parse a module with language FINNOGA.
- COMPILE=
- Member name of the load module for the Finnoga 4 parser. Note
that the keyword "COMPILE" actually identifies the load module name
of a translator (which may or may not be a compiler).
- DSNAME=
- Names the partitioned data set that contains the Finnoga 4 parser
load module. DSNAME is required when the data set containing the desired
module is not in the system concatenation. DSNAME is similar to a
STEPLIB.
When more than one data set is to be searched, the TASKLIB
parameter can be used in conjunction with, or as a replacement for,
the DSNAME parameter.
- PORDER=
- The value 1 tells SCLM that this program expects an options string
but not a ddname substitution list.
- OPTIONS=
- Specifies the options string to be passed to the parser. Strings
that start with @@FLM are SCLM variables, and they
are replaced by their current values before the string is passed to
the parser.
Since the parser reads its source from a ddname, you must tell
SCLM how to allocate that ddname. To do this, use an FLMALLOC macro
and an FLMCPYLB macro.
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMDSN(@@FLMMBR)
A description of the parameters follows:
- Parameter
- Description
- IOTYPE=A
- Tells SCLM to allocate a ddname to one, or a concatenation of,
specific data set(s). Each of those data sets are subsequently identified
by using an FLMCPYLB macro.
- DDNAME=
- Identifies the ddname to be allocated.
- @@FLMDSN(@@FLMMBR)
- Identifies the member to be parsed. When the two SCLM variables
are resolved, you get the member of the data set in which you are
interested.
Now you can tell SCLM how to invoke the Finnoga 4 compiler. To
do so, use an FLMTRNSL macro followed by one or more FLMALLOC and
FLMCPYLB macros.
FLMTRNSL CALLNAM='FINNOGA 4', C
FUNCTN=BUILD, C
COMPILE=FNGAA40, C
PORDER=3, C
GOODRC=0, C
OPTIONS='SOURCE,NOMACRO,OBJ(@@FLMMBR),', C
PARMKWD=PARM1
You can specify only a few of the parameters and let SCLM supply
default values for the others:
- Parameter
- Description
- CALLNAM=
- Names the compiler. This name appears in build messages.
- FUNCTN=
- Tells SCLM that this program gets invoked whenever you want to
build a member with language FINNOGA.
- COMPILE=
- Identifies the load module name for the Finnoga 4 compiler.
- DSNAME=
- If you do not specify a DSNAME value, SCLM assumes that the load
module can be found in the system concatenation.
- PORDER=
- The value 3 tells SCLM to pass an options string and a ddname
substitution list to the Finnoga 4 compiler.
- GOODRC=
- The value 0 indicates that SCLM is to consider this build unsuccessful
if the compiler completes with any return code greater than 0.
- OPTIONS=
- Specifies the options string to be passed to the compiler. At
compiler run time, the SCLM variable @@FLMMBR is resolved to the member
name being built.
- PARMKWD=
- The value PARM1 specifies the concatenation of the contents of
the PARM1 parameters in the architecture definition to the preceding
options string. Use the PARM1 parameter to specify the OPTIMIZE/NOOPTIMIZE
option for each member. An example of this is provided later in this
section.
As discussed previously, the Finnoga 4 compiler uses 7 ddnames
and also supports a ddname substitution list. The preceding parser
invocation definition showed how to define a translator (the parser)
that does not use a ddname substitution list. The following SCLM FLMALLOC
macros are used by SCLM to construct the ddname substitution list
shown in Table 1.
When you use a ddname substitution list, you must define the ddnames
in the order in which they are expected to appear in the ddname substitution
list by the translator. The first ddname defined is placed by SCLM
into position 1 in the ddname substitution list. The second ddname
specified is placed into position 2 in the ddname substitution list,
and so on.
Note that you do not have to specify any ddnames in the following
example macros. SCLM will create temporary unique ddnames and place
them into the ddname substitution list positions. Because of the way
ddname substitution lists work, the compiler uses those temporary
ddnames instead of the standard documented ddnames (like SYSIN).
The first ddname in the Finnoga 4's ddname substitution list is
SYSLIN. It is allocated to a partitioned data set into which the compiler
places the object module.
FLMALLOC IOTYPE=P,KEYREF=OBJ,DFLTTYP=OBJ,RECFM=FB,LRECL=80, C
RECNUM=5000
The parameters specified in this macro are described as follows:
- Parameter
- Description
- IOTYPE=P
- The compiler is written in such a way that a partitioned data
set must be allocated to this ddname. The compiler will write to a
member of this partitioned data set. SCLM creates a temporary PDS
and allocates it to a temporary ddname (since no DDNAME keyword was
specified).
This example illustrates two points. It shows how
to define a temporary PDS for output from a translator and emphasizes
that each compiler (or parser) that you define to SCLM may be slightly
different from any other translator you have defined to SCLM.
Always
refer to the translator documentation when defining a translator to
SCLM.
- KEYREF=OBJ
- To save what is written to this ddname and keep it under SCLM
control, SCLM must be able to determine the member name and the SCLM-controlled
data set name in which it is to save this output module. If SCLM is
building an architecture definition, it determines the project, group,
type and member as follows:
- The high-level qualifier is the project identifier that was previously
specified.
- The group is the level at which the build is taking place. The
group name is the second qualifier.
- SCLM looks at the architecture definition being built and retrieves
the member and type from the architecture statement associated with
the keyword OBJ. The type name is the third qualifier.
- DFLTTYP=OBJ
- To save what is written to this ddname and keep it under SCLM
control, SCLM must be able to determine the member name and the SCLM-controlled
data set name in which it is to save this output module. If SCLM is
building a source member, it determines the project, group, type and
member as follows:
- The high-level qualifier is the project identifier that was previously
specified.
- The group is the level at which the build is taking place.
- The type is the value of the DFLTTYP= keyword.
- The member name defaults to the name of the member being built.
If SCLM is building an architecture
definition (and not a source member directly) then the DFLTTYP= value
is ignored. Instead, SCLM uses the type associated with the KEYREF=
value.
- RECFM=FB
- Specifies the record format of the temporary data set that SCLM
creates. In this example, the record format is fixed block.
- LRECL=80
- Specifies the record length, in characters, of the temporary data
set that SCLM creates.
- RECNUM=5000
- Tells SCLM to allocate enough space in this data set to hold 5000
records (records that are fixed block and 80 characters in length).
Positions 2 and 3 in the ddname substitution list are not used.
Create two FLMALLOC macros with IOTYPE=N to tell SCLM to fill those
name fields with hex zeros and to continue to the next ddname.
FLMALLOC IOTYPE=N
*
FLMALLOC IOTYPE=N
The ddname in position 4 of the ddname substitution list must be
allocated to one or more partitioned data sets. This ddname is used
by the Finnoga 4 compiler to find included members. The
FLMINCLS macro
described earlier needs to be referenced here to ensure that the compiler
is picking up includes from the correct data sets. Since IOTYPE=I
allocations default to the default
include set shown
earlier, this is automatically done. If another name was used on the
FLMINCLS macro,
that name needs to be referenced here using the INCLS parameter. IOTYPE=I
allocates a ddname with a concatenation of all the PDS's in the hierarchy
starting with the group specified for the BUILD and ending with the
top, or production level, group. First the hierarchy for the INCLUDE
type is allocated, followed by the type of the first SINCed member
from the architecture definition, or, if no architecture definition
is used, the type of the member being built.
FLMALLOC IOTYPE=I,KEYREF=SINC
The parameters used with this macro are as follows:
- Parameter
- Description
- IOTYPE=I
- Allocate this ddname to a concatenation of SCLM-controlled data
sets. The types used in the concatenation are determined by the FLMINCLS macro
referenced by the INCLS= parameter on the FLMALLOC macro. In this
case, there is no INCLS= parameter so the default FLMINCLS (or include set) is
used.
A hierarchy of data sets is concatenated for each type specified
for the referenced FLMINCLS macro.
The hierarchy begins at the group where the build is taking place
and extends to the top of the project's hierarchy. In this case, the
concatenation first contains all of the data sets for the INCLUDES
type followed by the data sets for the value substituted into the
@@FLMTYP variable. See the KEYREF= parameter to determine the value
which is substituted into the @@FLMTYP and @@FLMETP variables.
- KEYREF=SINC
- If you are building an architecture definition, refer to the first
SINC statement in that architecture definition for the type that is
substituted into the @@FLMTYP macro. The value for @@FLMETP comes
from the EXTEND= parameter of the FLMTYPE macro for that type. If
you are not building an architecture definition, the type is the type
of the member being built.
The next ddname in the ddname substitution list is allocated to
the source to be compiled
FLMALLOC IOTYPE=S,KEYREF=SINC
The parameters used in the example are as follows:
- Parameter
- Description
- IOTYPE=S
- Tells SCLM to allocate a temporary sequential data set.
- KEYREF=SINC
- If you are building a source module directly, SCLM copies that
member to this temporary data set. If you are building a CC architecture
definition, SCLM copies the members listed on the SINC statement to
this data set.
Next, define the SYSPRINT ddname to SCLM.
FLMALLOC IOTYPE=O,KEYREF=LIST,RECFM=VBA,LRECL=125, C
RECNUM=5000,PRINT=Y,DFLTTYP=FINLIST
This definition contains the following parameters:
- Parameter
- Description
- IOTYPE=O
- Specifies that the compiler writes to this ddname using a sequential
data set. SCLM creates a temporary sequential data set and allocates
it to a temporary ddname (since this is part of a ddname substitution
list).
- KEYREF=LIST
- Refers SCLM to the LIST record in the architecture definition
being built. That record contains the member name and type into which
the listing is saved after a successful build. (SCLM copies the data
from the temporary data sets into members of the PDS's controlled
by SCLM after a successful build.)
- DFLTTYP=FINLIST
- Specifies the data set type into which this listing is written
whenever a Finnoga 4 module is built directly or when using INCLD
in an architecture definition.
- PRINT=Y
- Specifies that this is a listing that should be copied to the
Build List data set after the build process completes.
Although the next position in the ddname substitution list is not
used, you still need to tell SCLM what to put there. Create another
FLMALLOC with IOTYPE=N:
FLMALLOC IOTYPE=N
Next, specify the FINLIB data set allocation to SCLM. Specifically,
indicate that the Finnoga 4 library resides in a data set named SYS1.FINNOGA.LIB:
FLMALLOC IOTYPE=A
FLMCPYLB SYS1.FINNOGA.LIB
Finally, note that position 9 in the ddname substitution list,
like position 7, is not used:
FLMALLOC IOTYPE=N
The last two ddnames in the ddname substitution list for the Finnoga
4 compiler are temporary work data sets. Use IOTYPE=W for temporary
work data sets, such as SYSUT1, SYSUT2, and so on. In addition, specify
the record format and length of the two files, as shown in the following
example:
FLMALLOC IOTYPE=W,LRECL=4000,RECFM=F,RECNUM=4000
*
FLMALLOC IOTYPE=W,LRECL=4000,RECFM=F,RECNUM=4000
When you have completed all these steps you will have a language
definition similar to the following one. (Figure 1 contains
comments to explain the flow of operations.) When you are ready to
reassemble your project definition, add a COPY statement in your main
project definition file to include these macros.
Figure 1. Finnoga 4 Language Definition
(Part 1 of 2)**********************************************************
* FINNOGA 4 LANGUAGE DEFINITION
**********************************************************
*
FLMLANGL LANG=FINNOGA,VERSION=FINN4
*
**********************************************************
* TYPES TO SEARCH FOR INCLUDES
**********************************************************
*
FLMINCLS TYPES=(INCLUDE,@@FLMTYP)
*
**********************************************************
* PARSE TRANSLATOR DEFINITION
**********************************************************
*
FLMTRNSL CALLNAM='FINNOGA PARSER', C
FUNCTN=PARSE, C
COMPILE=FINPARSE, C
DSNAME=SCLM.PROJDEFS.LOAD, C
PORDER=1, C
OPTIONS=(@@FLMSIZ,@@FLMSTP,@@FLMLIS)
*
* -- SOURCE --
*
FLMALLOC IOTYPE=A,DDNAME=SOURCE
FLMCPYLB @@FLMDSN(@@FLMMBR)
**********************************************************
* BUILD TRANSLATOR DEFINITION
**********************************************************
*
FLMTRNSL CALLNAM='FINNOGA 4', C
FUNCTN=BUILD, C
COMPILE=FNGAA40, C
GOODRC=0, C
PORDER=3, C
OPTIONS='SOURCE,NOMACRO,OBJ(@FLMMBR),', C
PARMKWD=PARM1
*
* -- (1) OBJECT
*
FLMALLOC IOTYPE=P,KEYREF=OBJ,DFLTTYP=OBJ,RECFM=FB,LRECL=80, C
RECNUM=5000
*
* -- (2) NOT USED
*
FLMALLOC IOTYPE=N
*
* -- (3) NOT USED
*
FLMALLOC IOTYPE=N
*
* -- (4) INCLUDE LIBRARIES
*
FLMALLOC IOTYPE=I,KEYREF=SINC
*
* -- (5) SOURCE
*
FLMALLOC IOTYPE=S,KEYREF=SINC
*
* -- (6) LISTING
*
FLMALLOC IOTYPE=O,KEYREF=LIST,RECFM=VBA,LRECL=125, C
RECNUM=5000,PRINT=Y,DFLTTYP=FINLIST
Figure 2. Finnoga 4 Language Definition
(Part 2 of 2)*
* -- (7) NOT USED
*
FLMALLOC IOTYPE=N*
* -- (8) FINNOGA COMPILER LIBRARIES
*
FLMALLOC IOTYPE=A
FLMCPYLB SYS1.FINNOGA.LIB
*
* -- (9) NOT USED
*
FLMALLOC IOTYPE=N
*
* -- (10) WORK FILE
*
FLMALLOC IOTYPE=W,LRECL=4000,RECFM=F,RECNUM=4000
*
* -- (11) WORK FILE
*
FLMALLOC IOTYPE=W,LRECL=4000,RECFM=F,RECNUM=4000
*
*5665-402 (C) COPYRIGHT IBM CORP 1980, 1989