FLMALLOC macro

This macro provides these capabilities to SCLM:

Allocate temporary or permanent data sets that are used by translators.
FLMALLOC provides a limited equivalency to JCL DD or TSO ALLOCATE statements in your procedure libraries. The FLMALLOC parameters that provide this capability are BLKSIZE, CATLG, DDNAME, DIRBLKS, DISP, DSNTYPE, LRECL, RECFM, RECNUM, MEMBER, DINIT, MALLOC, and ALLCDEL. DINIT, MALLOC, and ALLCDEL indicate how the data set is to be dispositioned.

When allocating permanent data sets, use IOTYPE=A or I. When allocating temporary data sets, use IOTYPE=O, P, S, or W.

IOTYPEs A and I are used to associate a ddname with data sets that already exist.

IOTYPE H is used to associate a ddname with a z/OS® UNIX file. The file can be existing or new.

IOTYPE=S is used for input data from an SCLM-controlled library. The member in this library is copied into a temporary data set for use by the translator.

IOTYPE=O is used for output data to be stored in an SCLM-controlled data set. A temporary sequential data set is allocated for use by the translator and the output produced by the translator is copied into the member in the SCLM-controlled data set.

IOTYPE=P is used for output data to be stored in an SCLM-controlled library. A temporary partitioned data set is allocated for use by the translator and members produced by the translator are copied into an SCLM-controlled data set.

In general, if the translator writes to a sequential data set, use IOTYPE=O; if the translator writes to a member of a partitioned data set, use IOTYPE=P.

IOTYPE=W is used to allocate temporary data sets for use by the translator. These data sets are discarded at the completion of a BUILD or PROMOTE.

SCLM creates temporary data sets for the translators to use rather than allocating directly to the hierarchy data sets. This protects the integrity of the project hierarchy data when the translator is producing output that will be stored in the hierarchy. The output is copied from the temporary data sets to the project hierarchy after all the translators have been invoked. If multiple translators are invoked, DDNAMEs for the temporary outputs must be unique for each translator or only the outputs from the last translator will be copied.

All of the allocations for FLMALLOC macros that follow the FLMTRNSL macro are performed just before the translator is invoked. The exception to this rule applies when MALLOC=Y; see the description of MALLOC for details. The ordering of FLMALLOC macros in relation to FLMTRNSL macros is similar to the ordering of DD statements in relation to EXEC statements in JCL.

Temporary data sets that were created by SCLM are deleted when all of the build translators have completed processing for the member being built.
Control the contents of the ddname substitution list
The ddname substitution list is passed as a parameter to a translator that has PORDER=2 or 3. If PORDER=0 or 1, SCLM does not generate a ddname substitution list. Not all translators accept ddname substitution lists. If a translator does accept a ddname substitution list, the ddnames in the list are used to override the default ddnames used by the translator.

In addition to ddnames, sometimes the ddname substitution list specifies the name of a member to be created. This is true for the linkage editor used by SCLM. The linkage editor accepts the name of the member to be created as a parameter in the ddname substitution list. Valid FLMALLOC parameters for this capability are KEYREF and IOTYPE. Use IOTYPE=L to add a member name to its ddname substitution list.

Ddname substitution lists are generated through the use of FLMALLOC statements. Each FLMALLOC statement adds a ddname to the list. The order in which the ddnames appear in the list is defined by the order of the FLMALLOC statements.

For general information about ddname substitution lists, refer to "Invoking Utility Programs from an Application Program" in z/OS DFSMSdfp Utilities. See the manuals for the specific translator being invoked for details on the substitution list contents expected. For IBM® supplied compilers, this information is located in the compiler's Programmers Guide manual under "Invoking Compiler from Application Programs" or "Dynamic Invocation of Compiler".
Identify hierarchy data to be used or created by a translator
FLMALLOC can be used to identify information in the hierarchy that is either the input to a translator or the destination of the output from a translator.

The FLMALLOC parameters that are valid for this purpose are MALLOC, NOSAVRC, DFLTTYP, KEYREF, and LANG. The IOTYPE identifies whether the allocation is for input to or output from a translator. To identify the members of the hierarchy to use as input to a translator, use IOTYPE=S or A. To identify the temporary output data sets that SCLM should store in the hierarchy, use IOTYPE=O or P. If you want the information to be read from or saved in the project hierarchy, you must specify the KEYREF parameter, except for IOTYPE=S, which defaults to SINC.
Identify the translator data sets to be copied to a listing data set
Use the PRINT parameter to copy the contents of a temporary data set to the listing data set. A listing data set is a sequential data set that contains any list information returned from a translator. Listings can be created by the SCLM build, promote, parse, migrate, or save services and by SCLM Edit. See the PRINT parameter description for more information.
Use the output of one translator as input to another translator
This capability is used when one translator creates information that is required by another translator. This is only possible when multiple translators are defined for a language definition for the same function (FUNCTN=) value.

Use IOTYPE=U to indicate that the output from a previously called translator is to be used. See IOTYPE=U for more information.
Allows SCLM outputs specified with IOTYPE=O or P to be encoded. As a part of this encoding process the member is compressed to save space.

Macro format


>>-FLMALLOC--IOTYPE=-+-A-+--+---------------------+------------->
                     +-H-+  '-,BLKSIZE=block_size-'   
                     +-I-+                            
                     +-L-+                            
                     +-N-+                            
                     +-O-+                            
                     +-P-+                            
                     +-S-+                            
                     +-U-+                            
                     '-W-'                            

>--+---------------+--+----------------+------------------------>
   |         .-N-. |  '-,DDNAME=ddname-'   
   '-,CATLG=-+-Y-+-'                       

>--+-------------------------+--+-----------------------+------->
   '-,DFLTMEM=default_member-'  '-,DFLTTYP=default_type-'   

>--+---------------+--+---------------------------+------------->
   |         .-N-. |  '-,DIRBLKS=directory_blocks-'   
   '-,DINIT=-+-Y-+-'                                  

>--+----------------+--+-----------------------+---------------->
   '-,DISP=-+-OLD-+-'  |           .-PDS-----. |   
            +-SHR-+    '-,DSNTYPE=-+-LIBRARY-+-'   
            +-MOD-+                                
            '-NEW-'                                

>--+-------------------------+--+---------------------------+--->
   '-,INCLS=include_set_name-'  '-,KEYREF=keyword_reference-'   

>--+----------------+--+----------------------+----------------->
   '-,LANG=language-'  '-,LRECL=record_length-'   

>--+----------------+--+-----------------+---------------------->
   |          .-N-. |  |           .-N-. |   
   '-,MALLOC=-+-Y-+-'  '-,ALLCDEL=-+-Y-+-'   

>--+---------------------+--+---------------------+------------->
   '-,MEMBER=member_name-'  '-,NOSAVRC=no_save_rc-'   

>--+---------------------------+--+------------------------+---->
   '-,PATHOPT=uss_path_options-'  '-,PATHMDE=uss_path_mode-'   

>--+-------------------------------+---------------------------->
   '-,PATHDSP=uss_path_disposition-'   

>--+------------------------+--+---------------+---------------->
   '-,FILEDAT=uss_file_data-'  |         .-N-. |   
                               '-,PRINT=-+-Y-+-'   
                                         '-I-'     

>--+----------------------+--+---------------------------+------>
   '-,RECFM=record_format-'  '-,RECNUM=number_of_records-'   

>--+-------------+--+----------------+-------------------------><
   '-,VIO=-+-Y-+-'  '-,ENCODE=-+-Y-+-'   
           '-N-'               '-N-'

Parameters

IOTYPE=A|H|I|L|N|O|P|S|U|W

Specifies the type of data sets to be allocated and how these data sets can be used. FLMALLOC has different capabilities based on the IOTYPE assigned to it. Therefore, through the use of IOTYPEs, FLMALLOC is like nine different macros.

Figure 1 shows the language definition, FLM01ASM, which is delivered in the partitioned data set ISP.SISPSAMP. This sample is available as part of the ISPF product. Refer to this sample as necessary to understand the different IOTYPEs. Of course, not all IOTYPEs are used by any one language definition, but this will provide some aid in understanding most IOTYPEs.

Figure 1. Sample language definition for Assembler

***********************************************************************
*            HIGH LEVEL ASSEMBLER LANGUAGE DEFINITION FOR SCLM
*
* POINT THE FLMSYSLB MACRO(S) AT ALL 'STATIC' COPY DATA SETS
* ADD FLMCPYLB MACROS FOR EACH FLMSYSLB, TO THE 'SYSLIB' FLMALLOC MACRO
* CUSTOMIZE THE 'OPTIONS' AND 'GOODRC' FIELDS TO YOUR STANDARDS.
* ADD THE 'DSNAME' FIELD IF THE TRANSLATOR IS IN A PRIVATE LIBRARY.
* WHEN A NEW TRANSLATOR VERSION REQUIRES TOTAL RECOMPILATION FOR THIS
* LANGUAGE, THE 'VERSION' FIELD ON FLMLANGL SHOULD BE CHANGED.
***********************************************************************
ASM      FLMSYSLB SYS1.MACLIB
*
         FLMLANGL    LANG=ASM,VERSION=ASMV1.0
*
* PARSER TRANSLATOR
*
          FLMTRNSL   CALLNAM='SCLM ASM PARSE',                         C
               FUNCTN=PARSE,                                           C
               COMPILE=FLMLPGEN,                                       C
               PORDER=1,                                               C
               OPTIONS=(SOURCEDD=SOURCE,                               C
               STATINFO=@@FLMSTP,                                      C
               LISTINFO=@@FLMLIS,                                      C
               LISTSIZE=@@FLMSIZ,                                      C
               LANG=A)               *** THIS IS ASSEMBLER ONLY ***
*          (* SOURCE      *)
           FLMALLOC  IOTYPE=A,DDNAME=SOURCE
            FLMCPYLB @@FLMDSN(@@FLMMBR)
*
* BUILD TRANSLATOR(S)
*
*
*         --ASSEMBLER INTERFACE--
          FLMTRNSL   CALLNAM='ASSEMBLER',                              C
               FUNCTN=BUILD,                                           C
               COMPILE=ASMA90,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PORDER=1,                                               C
               OPTIONS=(XREF(SHORT),LINECOUNT(75),OBJECT,RENT)
*
* DDNAME ALLOCATIONS
*
 FLMALLOC  IOTYPE=S,DDNAME=SYSIN,KEYREF=SINC,RECNUM=5000
 FLMALLOC  IOTYPE=W,DDNAME=SYSUT1,RECNUM=17500
 FLMALLOC  IOTYPE=O,DDNAME=SYSLIN,KEYREF=OBJ,RECNUM=7500,DFLTTYP=OBJ
 FLMALLOC  IOTYPE=A,DDNAME=SYSTERM
  FLMCPYLB NULLFILE
 FLMALLOC  IOTYPE=A,DDNAME=SYSPUNCH
  FLMCPYLB NULLFILE
 FLMALLOC  IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC
* ADD ONE FLMCPYLB FOR EACH FLMSYSLB
  FLMCPYLB SYS1.MACLIB
 FLMALLOC  IOTYPE=O,DDNAME=SYSPRINT,KEYREF=LIST,PRINT=Y,               C
               DFLTTYP=LIST,RECNUM=20000
*
* 5694-A01 COPYRIGHT IBM CORP 1980, 2007

For the purpose of explanation, assume that any source modules built by sample architecture definitions given in these descriptions have been saved with the preceding language definition.

IOTYPE=A

Allocate a permanent data set or set of permanent data sets for either input or output. You need the FLMCPYLB macro to identify the data sets. There is an MVS™ limitation to the number of data sets that can be allocated to the ddname; the maximum is 123 data sets. The data sets allocated using this IOTYPE can be either partitioned or sequential. The default disposition is SHR. The DISP parameter can be used to override the default when a single data set is to be allocated. For example, you might use the override when you want to allocate a data set to be used for output with a disposition of OLD. If more than one data set is allocated, the DISP parameter must be SHR.

For example, in Figure 1, IOTYPE=A is used to allocate the SOURCE DDNAME. This identifies the source data set that will be used by the 'SCLM ASM PARSE' translator. If you use SCLM Edit to save member FLM01MD1 in type SOURCE and group DEV1 of project PROJ1, the FLMCPYLB statement identifies 'PROJ1.DEV1.SOURCE(FLM01MD1)' as the member to allocate as input to the parser.

IOTYPE=H

Allocate a z/OS UNIX file for either input or output. Use the FLMCPYLB macro to define the pathname. Additional requirements may be supplied using the PATHOPT, PATHMDE, PATHDSP, and FILEDAT parameters.

IOTYPE=I

Allocate libraries in the hierarchy for an include set. The INCLS parameter indicates the name of an include set as specified on an FLMINCLS macro. If no INCLS parameter is specified, the default include set is used.

A value should be specified for the KEYREF parameter or it will default to SINC and a warning message will be issued. The data sets allocated depend on the value of the KEYREF parameters:

For KEYREF=SREF, the hierarchy for the SREF type is allocated.
For KEYREF=CREF, the hierarchy for the CREF type is allocated.
For KEYREF=SINC, the INCLS parameter indicates that the types allocated are listed in the FLMINCLS macro for the include set. The FLMSYSLB data sets are allocated if ALCSYSLB=Y is specified on the FLMLANGL macro for the language, followed by any data sets specified on FLMCPYLB macros.
SCLM allocates all of the data sets for the types associated with the include set within the current view of the hierarchy. The starting group for the hierarchical view is defined by the group used as input to the function, rather than the group where the referenced member was found. The hierarchies for each type are allocated in the order specified on the FLMINCLS macro.

This allocation is typically used to resolve include dependencies when performing a compilation. FLMCPYLBs that follow this allocation should not reference SCLM-controlled data sets.

At least one data set must exist in the hierarchy for the types referenced.

For example, in Figure 1, IOTYPE=I with KEYREF=SINC is used to allocate the SYSLIB DDNAME. Because no INCLS parameter is specified for the IOTYPE=I, the default include set is used. In addition, because no FLMINCLS macro is specified for the default include set in this language definition, an FLMINCLS macro is generated with TYPES=(@@FLMTYP,@@FLMETP). If the example project hierarchy has been set up according to the steps identified in Project manager scenario, member FLM01CMD for 'PROJ1.RELEASE.ARCHDEF' contains these statements:

    *
    *
    * Object Module 1
    * OBJ FLM01MD1 OBJ
     LIST FLM01MD1 LIST
     SINC FLM01MD1 SOURCE
     PARM NOXREF,LC(75)

If a build was performed on this member at the DEV1 group, the FLMALLOC macro would indicate that a hierarchy should be allocated starting at the DEV1 group for the type indicated by the SINC card. In this case, 'PROJ1.DEV1.SOURCE', 'PROJ1.TEST.SOURCE', 'PROJ1.RELEASE.SOURCE', and 'SYS1.MACLIB' would be allocated.

If you were to look at the project definition for PROJ1, you would see this macro that defines the SOURCE type:

             SOURCE  FLMTYPE

Notice that there is no extend type defined. If, however, this type had been defined as follows:

             SOURCE  FLMTYPE EXTEND=SOURCE2

then building this member at the DEV1 group would have resulted in these data sets being allocated in order: 'PROJ1.DEV1.SOURCE', 'PROJ1.TEST.SOURCE', 'PROJ1.RELEASE.SOURCE', 'PROJ1.DEV1.SOURCE2', 'PROJ1.TEST.SOURCE2', 'PROJ1.RELEASE.SOURCE2', and 'SYS1.MACLIB'.

If the extended type SOURCE2 was defined as shown in the preceding macro, and a build was performed at the TEST group, these data sets would be allocated, in order: 'PROJ1.TEST.SOURCE', 'PROJ1.RELEASE.SOURCE', 'PROJ1.TEST.SOURCE2', 'PROJ1.RELEASE.SOURCE2', and 'SYS1.MACLIB'.

In this example, the default values have been used for the include set. If the FLMALLOC macro for IOTYPE=I had been written as follows, the include set of SYSLIB would have been used:

 FLMALLOC  IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC,INCLS=SYSLIB
* ADD ONE FLMCPYLB FOR EACH FLMSYSLB
  FLMCPYLB SYS1.MACLIB

In the previous example, the default values have been used for the include set and the FLMSYSLB data sets were not allocated. If the FLMLANGL macro had ALCSYSLB=Y and the FLMALLOC macro for IOTYPE=I had been written as follows, the include set of SYSLIB would have been used:

FLMALLOC  IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC,INCLS=SYSLIB
* COPYLIB ALLOCATION OF FLMSYSLB DATA SETS IS DONE AUTOMATICALLY

The FLMSYSLB macro would need to specify the include set using the INCLS parameter.

ASM    FLMSYSLB SYS1.MACLIB,INCLS=SYSLIB

An FLMINCLS macro is required in the language definition to indicate the types to be included in the allocation. This FLMINCLS macro first searches the MACROS type followed by the type and extended type.

* INDICATE THE TYPES TO SEARCH FOR THE SYSLIB INCLUDE-SET
SYSLIB    FLMINCLS TYPES=(MACROS,@@FLMTYP,@@FLMETP)

Using the preceding FLMINCLS macro, SCLM allocates data sets in this order for the SYSLIB ddname when building at group DEV1:

'PROJ1.DEV1.MACROS'
'PROJ1.TEST.MACROS'
'PROJ1.RELEASE.MACROS'
'PROJ1.DEV1.SOURCE'
'PROJ1.TEST.SOURCE'
'PROJ1.RELEASE.SOURCE'
'PROJ1.DEV1.SOURCE2'
'PROJ1.TEST.SOURCE2'
'PROJ1.RELEASE.SOURCE2'
'SYS1.MACLIB'

IOTYPE=L

Pass a member name in the ddname substitution list. See the PORDER parameter in FLMTRNSL macro for more information. The KEYREF parameter identifies the member name and type. This IOTYPE is commonly used to identify the load module name for the S/370 linkage editor.

Note: IOTYPE=L is only valid when the PORDER parameter in the FLMTRNSL macro is set to 2 or 3.

For example, Figure 1 is not a linkage editor language definition; therefore, it does not contain an example of IOTYPE=L. However, FLM01370 in ISP.SISPSAMP, part of the sample project definition, contains an example of IOTYPE=L. If the example project hierarchy has been set up according to the steps identified in Project manager scenario, member FLM01LD1 for 'PROJ1.RELEASE.ARCHDEF' contains these statements:

    *
    *   Load Module LMOD1
    *
    LOAD  FLM01LD1 LOAD
    LMAP  FLM01LD1 LMAP
    INCL  FLM01CMD ARCHDEF
    PARM  MAP,NCAL,
    PARM  LET

If a build was performed for this architecture definition, the FLMALLOC macro with IOTYPE=L and KEYREF=LOAD would pass "FLM01LD1" to the Linkage Editor.

IOTYPE=N

Skip over a field during ddname substitution. This IOTYPE is valid only for PORDER=2 or 3. SCLM adds 8 bytes of hexadecimal zeros to the ddname substitution list.

For example, this IOTYPE is not used by Figure 1, but if a translator accepted a ddname substitution list, using this IOTYPE on the FLMALLOC macro would result in 8 hexadecimal zeros being placed in the ddname substitution list.

IOTYPE=O

Allocate a sequential temporary data set that will contain output from a translator that is to be saved in the project hierarchy. A KEYREF parameter must be used to identify the output member name and type. Valid KEYREF values are OBJ, COMP, LIST, LOAD, LMAP, and OUTx.

Note: If the outputs of a translator are empty files then SCLM will copy the translator outputs into the hierarchy as empty members and create accounting records for these members.

For example, in Figure 1, IOTYPE=O is used to allocate the SYSPRINT DDNAME. This is a temporary data set into which the translator will write the Assembler listing. See the example for IOTYPE=I for an illustration of what is contained in architecture definition member FLM01CMD. If this member were built at DEV1, the build listing would be copied into the hierarchy into the member and type specified by the LIST card, FLM01MD1 LIST.

This example is building an architecture definition, so DFLTTYP will be ignored or overridden by the LIST card. If only the source were being built, the listing would go into the type specified by DFLTTYP.

IOTYPE=P

Allocate a temporary partitioned data set that will contain output from a translator that is to be saved in the project hierarchy. The dsntype parameter is used to indicate whether the temporary data set should be allocated as PDS or PDSE.

If the output from a translator is to be saved in the project hierarchy, then a KEYREF parameter must be used to identify the target member into which the translator output will be copied. Specify any output KEYREF value, such as KEYREF=LOAD or OUTx. If the output from a translator is not to be saved in the project hierarchy, do not specify a KEYREF parameter; this is essentially like using IOTYPE=W except that a partitioned data set is allocated for use by the translator instead of a sequential data set.

If the build is to occur on a workstation, use IOTYPE=P and DFLTMEM=* to take advantage of workstation build caching. IOTYPE=P preserves the workstation file's date and time information as it is copied to the host. If the output is needed as input for another build step, the date and time at the host member is compared the date and time of the corresponding workstation file. If they match, the file is considered to be the same, and the file is not transferred.

IOTYPE=P would be used when a translator requires a partitioned data set. If a translator accepted a sequential data set, IOTYPE=O would be used.

SCLM determines the names of the members to be copied into the project hierarchy from the architecture definition being built or from the DFLTMEM parameter on the FLMALLOC macro. If an architecture definition member is being built, the name specified in that member is used. If a source member is being built directly or as a result of an INCLD architecture statement, the DFLTMEM parameter on the FLMALLOC macro is used.

If an asterisk is specified for the output member name in the architecture definition, or no DFLTMEM parameter is specified, then all members in the temporary data set are copied into the project hierarchy. Otherwise, only the member that matches the name on the architecture statement or DFLTMEM parameter is copied into the project hierarchy.

For example, Figure 1 does not contain an example of IOTYPE=P. However, if the Assembler, ASMA90, had required a partitioned data set for the object module instead of a sequential data set, then the FLMALLOC for the SYSLIN DDNAME would have used IOTYPE=P instead of IOTYPE=O.

IOTYPE=S

Allocate a temporary sequential data set and create the input stream for the translator by concatenating the contents of all the members that are SINCed as well as any text specified via CMD cards. Concatenation will occur in the order specified by the architecture definition. Use the KEYREF parameter to identify the members from the project hierarchy that will be used to create the input stream.

When these criteria are met, SCLM allocates the PDS member directly from the SCLM-controlled library, rather than copying the member first to a sequential data set. The criteria are:

There is only one input
The input is from a SINC statement
The KEYREF on the FLMALLOC statement is SINC
you are not doing input list processing.

Any user-defined translators must take into account that the DDNAME allocated might be either a sequential data set or a PDS member.

For example, in Figure 1, IOTYPE=S is used to allocate the data set that will contain the input stream for the translator SYSIN. See the example for IOTYPE=I for an illustration of what is contained in architecture definition member FLM01CMD. If this member were built at DEV1, the SYSIN data set would contain a copy of member FLM01MD1, type SOURCE. If more than one SINC card had been specified, then the source referenced by subsequent SINC cards would have been appended to the end of SYSIN in the order specified in the architecture definition.

IOTYPE=U

Any preallocated ddname that matches the DDNAME parameter value will be used. There will be no new ddname allocation. This is typically used for referring back to a preallocated ddname from a previous FLMALLOC following a previous FLMTRNSL in the same language definition. In this situation the DDNAME parameter values need to be the same.

ddname substitution lists are useful in situations in which more than one translator is defined for a language and one translator needs to use the output from a previous translator. This latter translator would have an FLMALLOC statement with IOTYPE=U and the same DDNAME parameter value as the previous FLMALLOC for a previous FLMTRNSL in the same language definition. In order to use ddname substitution lists the translator must be programmed to handle the ddname substitution list and the FLMTRNSL must have a PORDER value of 2 or 3 to construct and pass the list to the translator.

Translators that are programmed to use ddname substitution lists include some compilers, linkage editors, and utilities. These translators will use the DDNAME parameter value for a data set. If the DDNAME parameter is not specified the system will generate a ddname for use in the ddname substitution list.

For PORDER values of 0 or 1 SCLM does nothing. There are no additional file allocations. At execution time the translator will use whatever data set has been allocated to the ddname specified by the translator program.

For example, Figure 1 does not use IOTYPE=U. The sample language definition for the assembler language only calls one build translator. However, if this language definition had called a preprocessor and had PORDER=2 or 3, as shown in Figure 2, the assembler compiler, ASMA90, would want to use the output from the preprocessor, IFPRE0. It would not be necessary for ASMA90 to create a data set that would contain the input stream because this has been prepared by IFPRE0.

Figure 2. Sample language definition that calls a preprocessor

*
* BUILD TRANSLATOR(S)
*
*
*    --CREATE THE INPUT STREAM FOR THE ASSEMBLER COMPILER--
*
*         --ASSEMBLER PREPROCESSOR--
          FLMTRNSL   CALLNAM='ASM PREPROCESSOR',                       C
               FUNCTN=BUILD,                                           C
               COMPILE=IFPRE0,                                         C
               PORDER=3,                                               C
               OPTIONS=(GROUP=@@FLMGRP,                                C
               TYPE=@@FLMTYP,                                          C
               MEMBER=@@FLMMBR)
*
* DDNAME ALLOCATIONS
*
           FLMALLOC  IOTYPE=W,RECFM=FB,LRECL=80,                       C
               RECNUM=9000,DDNAME=SYSIN
* --CALL THE ASSEMBLER COMPILER TO PROCESS INPUT--
*
*         --ASSEMBLER INTERFACE--
          FLMTRNSL   CALLNAM='ASSEMBLER',                              C
               FUNCTN=BUILD,                                           C
               COMPILE=ASMA90,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PORDER=3,                                               C
               OPTIONS=(XREF(SHORT),LINECOUNT(75),OBJECT,RENT)
*
* DDNAME ALLOCATIONS
*
 FLMALLOC  IOTYPE=O,DDNAME=SYSLIN,KEYREF=OBJ,RECNUM=7500,DFLTTYP=OBJ
 FLMALLOC  IOTYPE=N
 FLMALLOC  IOTYPE=N
 FLMALLOC  IOTYPE=I,DDNAME=SYSLIB,KEYREF=SINC
 * ADD ONE  FLMCPYLB FOR EACH FLMSYSLB
  FLMCPYLB SYS1.MACLIB
 FLMALLOC  IOTYPE=U,DDNAME=SYSIN
 FLMALLOC  IOTYPE=O,DDNAME=SYSPRINT,KEYREF=LIST,PRINT=Y,               C
  DFLTTYP =LIST,RECNUM=20000
 FLMALLOC  IOTYPE=A,DDNAME=SYSPUNCH
  FLMCPYLB NULLFILE
 FLMALLOC  IOTYPE=W,DDNAME=SYSUT1,RECNUM=15000
 FLMALLOC  IOTYPE=N
 FLMALLOC  IOTYPE=N
 FLMALLOC  IOTYPE=N
 FLMALLOC  IOTYPE=A,DDNAME=SYSTERM
  FLMCPYLB NULLFILE
 *

IOTYPE=W

Allocate a temporary sequential data set for translator use. SCLM uses the RECFM, LRECL, and RECNUM parameters for allocation of this data set. If they are not specified, SCLM uses the defaults.

For example, Figure 1 uses IOTYPE=W to allocate SYSUT1. When the Assembler, ASMA90, is invoked, a sequential data set is created and allocated to DDNAME SYSUT1. This data set is used internally by the assembler and it is not necessary to store it in the project hierarchy. This language definition does not print the contents of this data set to the build listing data set because the PRINT keyword was not specified and defaults to N.

When all build translators for this language have completed processing, SYSUT1 will be deleted. In the preceding example, when the assembler has completed and returned control to build, build will deallocate the data set associated with SYSUT1.

The position of the FLMALLOC macros is very important because SCLM can pass ddnames directly to the translator; see the PORDER field description. SCLM passes ddnames to the translator in the order of the FLMALLOC macros.

SCLM deallocates temporary data sets after all translators for a particular member and a particular function (for example, FUNCTN=BUILD, COPY, and PURGE specified in the FLMTRNSL macro) for a particular language have completed processing.

To use the output from one translator step as input to another translator step, add (or modify) an FLMALLOC macro for the second translator step with IOTYPE=U and DDNAME=ddname allocated for the first translator step. Be careful when adding FLMALLOC macros for the second translator step. Depending on the PORDER that is specified in the FLMTRNSL macro, it may be necessary to put the new FLMALLOC macro in a particular position in the list of FLMALLOC macros. See the documentation for the particular compiler or translator you are calling to determine whether it accepts ddname substitution lists and, if so, what order it expects the parameters to be passed.

Table 1 indicates the valid IOTYPEs for each function. Note that all IOTYPEs are valid for a build, and that IOTYPEs A, U, and W are valid for all functions.

Table 1. Valid IOTYPEs for each function
IOTYPE	Build	Copy	Parse	Purge	Verify
A	X	X	X	X	X
I	X
L	X
N	X
O	X
P	X
S	X
U	X	X	X	X	X
W	X	X	X	X	X

,BLKSIZE=block_size

Block size of the data set. This parameter is valid for IOTYPE=W, O, P, and S. If this parameter is not specified or is specified as 0 (zero), then the block size used is the largest integral multiple of the LRECL values that is less than or equal to 3120. It is recommended that this value match the block size of the target data set for IOTYPE=P and RECFM=U. This parameter is ignored for IOTYPE=A, I, L, N, and U.

The IBM linkage editor requires that the DCBS option parameter be passed in order for the SYSLMOD block size to be used in creating load modules. If the DCBS option is not specified, the linkage editor creates load modules using the maximum record size for the device type. Use the OPTIONS= parameter on the FLMTRNSL macro to pass the DCBS option. Failure to do so can result in message FLM44507.

,CATLG=N|Y

Indicates whether a data set is to be cataloged. Valid for IOTYPE=W, O, P, and S. SCLM temporarily allocates cataloged data sets with a predefined high-level qualifier, the TSO-prefix. The data set is deleted after all translators complete their functions. The default is N.

,DDNAME=ddname

The ddname to be used for this allocation. If you do not specify a ddname for the allocation, SCLM generates one for you. If the PORDER parameter in FLMTRNSL has the value of 0 or 1, a nonblank value is required for DDNAME.

A special case occurs when MALLOC=Y is specified. Because MALLOC=Y implies more than one allocation, you must allow SCLM to generate ddnames for these allocations. If PORDER=2 or 3, SCLM generates a ddname if the parameter is omitted. This parameter is not used for IOTYPE=L or IOTYPE=N.

Do not reuse the same ddname in multiple-step language definitions unless you intend to pass data from one step to the next using IOTYPE=U. If the same DDNAME is used for multiple translators, only the outputs from the last translator will be copied to the hierarchy.

,DINIT=N|Y

Indicates whether SCLM should create a member in a temporary data set allocated with IOTYPE=P. DINIT is ignored for all IOTYPEs except P. If DINIT=Y, SCLM initializes the member with a single record containing the string "DUMMY FILE" beginning in column 1. The member created will have the same name as the build map that is created if the translator is successful. If the MEMBER parameter is specified, its value will be used to determine the name of the member to initialize. If the MEMBER parameter is not specified, the member initialized will be the member to be saved in the hierarchy. If the member will not be saved in the hierarchy, the member initialized will have the same name as the source or architecture definition controlling the build.

,DIRBLKS=directory_blocks

The number of directory blocks allocated to the data set if the data set is partitioned (IOTYPE=P). For IOTYPE=P, the default is 1 and for all other IOTYPEs, the default is 0. SCLM will ignore nonzero values for all IOTYPES except IOTYPE=P.

,DISP= OLD|SHR|MOD|NEW

Optional parameter used to identify the disposition for the allocation on a DD card in JCL. Valid values are OLD, SHR, MOD, NEW. If not specified, the disposition defaults to an appropriate value for the IOTYPE parameter, as described in Table 2.

Table 2. Valid DISP values for IOTYPE values
IOTYPE	Default	Valid Values	Condition
A	SHR	SHR,MOD,OLD	With a single copylib
A	SHR	SHR	With multiple copylibs
A	SHR	SHR,OLD	With MALLOC=Y
H	n/a	n/a
I	SHR	SHR
L	n/a	n/a
N	n/a	n/a
O	OLD	NEW,MOD
O	SHR	SHR,OLD	With MALLOC=Y
P	NEW	NEW
S	MOD	MOD
U	n/a	n/a
W	NEW	NEW,MOD

The DISP parameter applies to the temporary data set created by SCLM instead of the controlled members in the hierarchy for IOTYPE O and P. See the z/OS TSO/E Command Reference for more information.

This parameter is ignored for IOTYPE L, N, and U.

,DFLTMEM=default_member

Indicates the name for the output member. Use IOTYPE=O or P to allocate data sets that will be used for translator outputs. If this parameter is not used, the output member name for IOTYPE=O will be the same as the source member; for IOTYPE=P all output members will be copied using the translator-generated member names. SCLM ignores this field during a build if you use an architecture definition member to build the source member. If you are using an architecture definition member, define the translator outputs with an output keyword such as OBJ, OUTx, or LOAD. DFLTMEM is ignored unless:

KEYREF is specified with a valid output keyword.
DFLTTYP is specified.
IOTYPE is either O or P.

The name of the translator output can be based on the name of the source input by using an asterisk as a special match character. The asterisk is replaced by the name of the source member. If the substitution of the source name would result in a name longer than 8 characters, the source name is truncated to produce an 8-character name. For example, if the DFLTMEM parameter is *FM, a source member of EX00G would cause the output to be stored in name EX00GFM.

,DFLTTYP=default_type

Indicates the name of the SCLM type for translator outputs. Use IOTYPE=O or P to allocate data sets that will be used for translator outputs. The output member name is the same as the source member. SCLM ignores this field during a build if you use an architecture member to build the source member. If you are using an architecture member, define translator outputs with an output keyword such as OBJ, OUTx, or LOAD. DFLTTYP is ignored if no KEYREF is specified.

The type for the translator output can be based on the type of the source input by using an asterisk as a special match character. The asterisk is replaced by the type of the source member. If the substitution of the source type would result in a name longer than 8 characters, the source type is truncated to produce an 8-character result. If the DFLTTYP parameter is *LST, a source type of SRC1 would cause the output to be stored in type SRC1LST. The type specified on this parameter, or the type generated if an asterisk is used, must be defined to the project definition with the FLMTYPE macro. No verification of this parameter is performed when the project definition is generated.

,DSNTYPE=PDS|LIBRARY

Determines whether a temporary partitioned data set (IOTYPE=P) is allocated as a PDS or PDSE. Use DSNTYPE=LIBRARY to have the data set allocated as a PDSE. If you specify DSNTYPE=LIBRARY and your system or project specifies that temporary data sets should be allocated to VIO, then add the CATLG=Y parameter to the FLMALLOC macro. This parameter is only valid for IOTYPE=P. The default value is PDS.

,INCLS=FLMINCLS_name

Refers to an FLMINCLS macro in the language definition that lists the types to be allocated. If the FLMLANGL macro for the language has ALCSYSLB=Y, the FLMSYSLB data sets for the include set will be allocated after the data sets from the project. This parameter is only valid for IOTYPE=I. If no INCLS= parameter is specified for IOTYPE=I, the default include set is used to determine the types for allocation.

,KEYREF=keyword_reference

Refers to a keyword in the build map or architecture definition. The member name and type (as denoted in the build map or architecture definition) associated with the keyword are used by other parameters in this macro:

If IOTYPE=L, keyword_reference identifies the member name the macro passes in the ddname substitution list for the translator.
If IOTYPE=S, keyword_reference identifies the input members for the translator. For LEC architecture members, the contents of the temporary data set will depend on the KEYREF specified. If KEYREF is specified as INCL, an include statement in a format used by the S/370 linkage editor will be generated for each object member or load module referenced. If KEYREF is specified as SINC, the contents of each object member referenced or generated by SCLM will be copied into the temporary data set. This does not include any object modules referenced by the SCLM LINK command. LINK will cause an "INCLUDE" link-editor command to be included in the temporary data set. S/370 linkage editor include statements are generated for each load module specified as input. This is true when KEYREF=SINC or KEYREF=INCL. Although it will take longer to process KEYREF=SINC, this can be used to handle object members having large block sizes or containing linkage edit control statements.
If IOTYPE=I, keyword_reference determines the type name of the hierarchy to allocate. The keywords that can be used with IOTYPE=I are SINC, SREF, and CREF.
If IOTYPE=O or P, keyword_reference identifies the location in the hierarchy for build to copy the output created by the translator if the translator is successful. The keywords that can be used with IOTYPE=O or P are COMP, LIST, LMAP, LOAD, OBJ, and, OUTx.

,LANG=language

Allows a build output to be assigned a different language than the build input. If this parameter is not specified, then build outputs are assigned the same language as inputs.

This parameter is not necessary when you can create in a single build all the build outputs you want.

Use this parameter when you want the build output of one language definition to be verified, built, copied, or purged in another language definition.

,LRECL=record_length

Logical record length of the data set (numeric). It is valid for IOTYPE=W, O, P, and S. The default is 80. It is recommended that this value match the LRECL of the target data sets for IOTYPE=O or P.

,MALLOC=N|Y

Use MALLOC=Y when the translator generates a sequential output data set that has a specific data set name and cannot be allocated to a ddname before the translator is invoked. This condition might occur if the translator performs its own allocations and always creates a data set with a specific name. Input list translators are required to generate output data sets that can be captured with this type of allocation. For input list processing, one allocation is performed for each member processed on the input list.

When you specify the FLMALLOC macro with MALLOC=Y, you must also specify an FLMCPYLB macro that identifies the name of the data set to be allocated.

An FLMALLOC with MALLOC=Y is ignored for all iotypes except O and A. If MALLOC=Y and IOTYPE is not an A and not an O, an error message is produced. The KEYREF parameter must be specified on the FLMALLOC for the allocation to occur. If MALLOC=Y is specified, the ddname parameter must be blank.

,ALLCDEL=N|Y

Indicates that all data sets referenced by this FLMALLOC macro should be deleted when SCLM has finished processing them. For example, specify ALLCDEL=Y to indicate that the output listings from the Input List translator should be deleted after they are copied into the hierarchy. The ALLCDEL parameter is ignored unless MALLOC=Y is specified.

,MEMBER=member_name

Causes a ddname to be allocated to a member of a temporary partitioned data set created by SCLM. This parameter is valid only for IOTYPE=P.

The member name can be evaluated dynamically by specifying @@FLMONM or @@FLMMBR as the parameter value. If a KEYREF OUTx parameter is specified and the architecture definition has a matching OUTx statement, then SCLM uses the output member name in the architecture definition. If no OUTx architecture statement is specified, then SCLM uses the name of the member being built. This can be the name of an architecture definition or the name of a build input.

This parameter is not necessary for most translators. However, some translators must know the name of the output member.

,NOSAVRC=no_save_rc

A return code value set by a translator that indicates whether SCLM is to store a translator output in this data set. This parameter is valid for IOTYPE=O and P. SCLM provides this feature to handle translators that, by design, have missing or static outputs. If it is decided that these outputs need not be saved for some situations, then the translators can be written to recognize these situations and return an appropriate return code. Through the use of this return code and the NOSAVRC parameter, SCLM will be able to determine when the output should be saved in the hierarchy and when it should not. This helps avoid unnecessary rebuilds of some build components. This parameter, if specified, must have a nonzero positive value; if not specified, the default is zero.

Note: An example is a translator that can differentiate "comment only" changes from code changes and determine which outputs are not affected. A listing is updated but not OBJECT code. SCLM can use this information to avoid unnecessary work.

,PATHOPT=uss_path_options

Specify a list of access and status options for a z/OS UNIX file allocation. Up to seven option keywords, separated by commas, can be specified. Only one keyword from the access group can be specified.

Access keywords are:


>>-+-ORDONLY-+--,----------------------------------------------><
   +-OWRONLY-+      
   '-ORDWR---'

Status keywords are:


>>-+----------+--+---------+--+--------+--+---------+----------->
   '-,OAPPEND-'  '-,OCREAT-'  '-,OEXCL-'  '-,NOCTTY-'   

>--+-----------+--+--------+--+--------+-----------------------><
   '-,NONBLOCK-'  '-,OSYNC-'  '-OTRUNC-'

See the PATHOPTS parameter in z/OS MVS JCL Reference for more details.

,PATHMDE=uss_path_mode

Specify file access attributes when creating a z/OS UNIX file. Up to 14 keywords, separated by commas, can be specified.

Keywords =

SIRUSR SIWUSR SIXUSR SIRWXU SIRGRP SIWGRP SIXGRP
SIRWXG SIROTH SIWOTH SIXOTH SIRWXC SISUID SISGID

See the PATHMODE parameter in z/OS MVS JCL Reference for more details.

,PATHDSP=uss_path_disposition

Specify file disposition when allocating a z/OS UNIX file. The syntax is:


>>-+--------------------+--,-+----------------------+----------><
   '-normal_disposition-'    '-abnormal_disposition-'

where either disposition can be KEEP or DELETE.

See the PATHDISP parameter in z/OS MVS JCL Reference for more details.

,FILEDAT=uss_file_data

Specify the organisation of a z/OS UNIX file. Either TEXT or BINARY can be specified. BINARY indicates a byte-stream data with no record delimiters. TEXT indicates that the data contains records delimited by the EBCDIC newline character (X'15').

See the FILEDATA parameter in z/OS MVS JCL Reference for more details.

,PRINT=N|Y|I

Indicates whether the contents of a sequential data set are to be copied to the SCLM listings data set (userid.BUILD.LISTxx). The contents will only be copied in the case of an error when the error listings only field is selected on the build panel. This parameter is only valid for data sets allocated with IOTYPE=W, S, or O. The valid values are:

N: indicates the contents of the temporary sequential data set are not to be copied to the listings data set. This is the default setting.
Y: indicates that the contents of the temporary sequential data set are to be copied to the listings data set.
I: indicates that the contents of the temporary sequential data set are to be copied to the listings data set. SCLM will open and close the temporary data set before invoking the translator.

Data sets allocated with PRINT=Y must be opened by the translator. Otherwise, an ABEND can occur when SCLM attempts to copy the contents to the build listings data set. For data sets that will not be opened by the translator, use PRINT=I. As PRINT=I adds an open and close, build performance can be slightly degraded.

,RECFM=record_format

Record format of the data set. It is valid for IOTYPE=W, O, P, and S. Valid values are F, FA, FM, FB, FBA, FBM, V, VA, VM, VB, VBA, VBM, and U; the default is FB (fixed blocks). It is recommended that this value match the RECFM of the target data sets for IOTYPE=O or P.

,RECNUM=number_of_records

Number of records to be allocated (numeric). It is valid for IOTYPE=W, O, P, and S. The default is 500.

This parameter is used in the calculation of the primary and secondary space allocations required for the temporary data set. Space allocations are in blocks and the number of blocks is determined by the number of records using this formula:

(((number_of_records / ((3120 / record_length) + 1)) + 1) / 16) + 1

,VIO=Y|N

Overrides the selection for use of VIO. Y causes the data set to always be allocated using VIO; N causes the allocation to never use VIO. The default is to determine use of VIO by comparing the RECNUM specification to the value for MAXVIO on the FLMCNTRL macro.

Note: The Automatic Class Selection (ACS) routines defined for a DFSMS installation can override the selection requested by SCLM. Contact your site's system programmer for information about how these will interact on your system.

,ENCODE=Y|N

Specifies whether a member is encoded when it is saved. The parameter ENCODE=Y can only be specified if IOTYPE=O or P has been specified on the FLMALLOC macro. SCLM, when copying the temporary data set and member to the SCLM controlled library, encodes the member when it is saved.

Defining a software component using the FLMALLOC macro

You can specify a software component either with an architecture member or with the FLMALLOC macros you specified in the language definition. For example, the language definition for member xxxxxxxx in type SOURCE contains these FLMALLOC macros:

    FLMALLOC IOTYPE=S,KEYREF=SINC
    FLMALLOC IOTYPE=O,KEYREF=LIST,DFLTTYP=LISTING
    FLMALLOC IOTYPE=O,KEYREF=OBJ,DFLTTYP=OBJECT

Building the member is the same as building this architecture definition:

    SINC xxxxxxxx SOURCE
    LIST xxxxxxxx LISTING
    OBJ  xxxxxxxx OBJECT

Always use the SINC keyword (on the KEYREF= parameter of the FLMALLOC macro) to identify the input member. If you need multiple SINC keywords, you must use an architecture member to specify the software component. Options to override the translator options (using the PARM and PARMx keywords) also require that you use an architecture member. You can also use the fields DFLTCRF and DFLTSRF on the FLMLANGL macro to identify the types to use in resolving source dependencies.

Example 1

Two data sets are allocated: one to contain the input stream (IOTYPE=S), the other to contain the output from the translator (IOTYPE=O). The input stream is the member you specify on the SINC statement of an architecture member. The output is copied to the member specified with the LIST statement of an architecture member. The output is also copied to the listing data set for the SCLM function.

     FLMALLOC IOTYPE=S,KEYREF=SINC,RECNUM=5000,LRECL=80,RECFM=FB

     FLMALLOC IOTYPE=O,KEYREF=LIST,RECNUM=5000,LRECL=133,RECFM=VBA,  X
         PRINT=Y

Example 2

The hierarchy for the type specified on the SINC statement of an architecture member is allocated. Two additional data sets are allocated after the hierarchy by the FLMCPYLB macro.

      FLMALLOC IOTYPE=I,KEYREF=SINC
      FLMCPYLB SYS1.LINKLIB
      FLMCPYLB SYS1.MACLIB

Example 3

The temporary partitioned data set (IOTYPE=P) that will contain the translator output to be saved into the project hierarchy will be allocated as a PDSE.

   FLMALLOC  IOTYPE=P,KEYREF=LOAD,RECFM=U,LRECL=0,                 X
      BLKSIZE=6144,RECNUM=5000,DIRBLKS=200,DDNAME=SYSLMOD,         X
      DSNTYPE=LIBRARY