z/OS ISPF Software Configuration and Library Manager Guide and Reference
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Defining a new language: step-by-step

z/OS ISPF Software Configuration and Library Manager Guide and Reference
SC19-3625-00

The following list briefly describes the process required to write a new SCLM language definition:

  1. Define the language name to SCLM.
  2. Define include-sets for the language to identify the locations of included members.
  3. List the various programs (parsers, compilers, and so on) used to parse and build your source.
  4. 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.
  5. 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.
  6. 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.
  7. 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
Parent topic: Using DDnames and DDname substitution lists

Go to the previous page Go to the next page

Notices | Terms of use | Support | Contact z/OS | zFavorites



Copyright IBM Corporation 1990, 2014