gtps4m2bSystem Generation

Preparing for Stage I

Before SIP stage I can be executed, perform the tasks as outlined in the following paragraphs, depending on your system needs. Special attention should be given to Creating Program Tables and Creating a Site System Allocator.

Stage II Job Card

During stage I execution, a job card will be constructed for each stage II job. This is done by accessing a member (SPJOB) of the ACP.SIPGEN.RELvv data set. This member must be modified according to your needs by adding such items as accounting information or other special functions.

Note:
Use extreme care whenever updating this member because variable symbols are assigned during stage I.

SYSPUNCH Output

If the output of stage I is going to tape, an output tape must be initialized, labeled and defined in the stage I JCL SYSPUNCH data definition (see example in Sample SIP Stage I Input).

LISTAPE Output

If the LISTAPE parameter of the GENSIP macro is coded (for tape output of multiple assembler), output tapes must be initialized and labeled to conform to the values of the LISTAPE parameter of the GENSIP macro. You may specify volume serial numbers or scratch for each tape. These tapes should be standard label tapes.

ICKDSF Data Set Initialization

ICKDSF allocates and initializes a whole disk storage volume. Once the disk pack is scratched, data sets are allocated on it for the various TPF required files. Special attention should be given to the allocated block size of the FACE table to be generated. The following JCL describes the necessary steps.

  1. The following JCL describes the ICKDSF run for a volume that is not online to MVS.
    //INITDISK EXEC PGM=ICKDSF
    //SYSPRINT DD SYSOUT=A
    //SYSIN  DD *
     INIT UNITADDRESS(xxxx) VTOC(0,1,10) -
           VOLID(yyyy) NOVERIFY
     
       where xxxx = the channel and unit address of the volume to be
                    initialized.
             yyyy = volume serial label of the disk volume
    
  2. The following JCL describes initializing a volume mounted online to MVS.
    //INITDISK EXEC PGM=ICKDSF
    //SYSPRINT DD SYSOUT=A
    //CUU      DD DSN=SIPFILES,DISP=OLD,UNIT=xxxx,
                  VOL=SER=yyyy
    //SYSIN    DD *
        INIT DDNAME(CUU),VTOC(0,1,10) VOLID(zzzz) -
               NOVERIFY
        where xxxx = device unit number which the volume is mounted on
              yyyy = volume serial of the volume to be initialized
              zzzz = volume serial label of the disk volume
    
  3. The following JCL should be run to scratch any data sets on the volume.
    //SCRATCH EXEC PGM=IEHPROGM
    //DD0     DD  UNIT=xxxx,VOL=SER=yyyy,DISP=OLD
    //SYSIN   DD *
        SCRATCH VTOC,VOL=xxxx=yyyy,PURGE
    /*
         where xxxx = device unit number which the volume is mounted on
               yyyy = volume serial of the volume to be scratched
    
  4. Create the SIP output data sets. The values coded for SPACE are only guidelines.

    Notes:

    1. xx = TPF release level. It must be the same as the value coded on the RELNN parameter of the GENSIP macro in stage I.

    2. yyyy = subsystem name. It must be the same as the value coded on the SSNAME parameter of the SSDEF macro in stage I or blank if SSDEF is not coded.

    3. zzzzz = volume serial number of an MVS volume.

    4. uuuu = unit.

    5. The block size for ACP.LINK.RELxx.yyyy must be understood in relation to the size of the FACE table to be generated. This relationship is:
      BLKSIZE * 512 >= the size of the largest FACE Table
      

      So, determine the size of the largest FACE table potentially to be used and divide by 512. The resulting number is the smallest BLKSIZE that can be used.

  5. Compile and link-edit the FACE table generator (see Compiling the FACE Table Generator for more information).

Figure 27. JCL for Allocating TPF Data Sets


//ALLOC EXEC PGM=IEFBR14
//DD1   DD  DSN=ACP.OBJ.RELxx.yyyy,
//         SPACE=(TRK,(850,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD2   DD  DSN=ACP.LINK.RELxx.yyyy,
//         SPACE=(TRK,(400,20)),
//         DISP=(,CATLG),DCB=(RECFM=U,LRECL=80,BLKSIZE=1200),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD3   DD  DSN=ACP.SYMACRO.RELxx.yyyy,
//         SPACE=(TRK,(200,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD4   DD  DSN=ACP.SYSRCE.RELxx.yyyy,
//         SPACE=(TRK,(150,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD5   DD  DSN=ACP.SALTBL.RELxx.yyyy,
//         SPACE=(TRK,(20,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=12,BLKSIZE=3504),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD6   DD  DSN=TPFxx.ANTS.yyyy,
//         SPACE=(TRK,(20,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD7   DD  DSN=ACP.CLIB.RELxx.yyyy,
//         SPACE=(TRK,(850,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD8   DD  DSN=ACP.STUB.RELxx.yyyy,
//         SPACE=(TRK,(850,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD9   DD  DSN=ACP.IMPORTS.RELxx.yyyy,
//         SPACE=(TRK,(75,15,25)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz

Figure 28. JCL for Allocating TPFDF Data Sets


//ALLOC EXEC PGM=IEFBR14
//DD1   DD  DSN=BDF.V1R1M3.BDFOBJ1.yyyy
//         SPACE=(TRK,(400,20)),
//         DISP=(,CATLG),DCB=(RECFM=FB,LRECL=80,BLKSIZE=400),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz
//DD2   DD  DSN=BDF.V1R1M3.BDFLNK1
//         SPACE=(TRK,(400,20)),
//         DISP=(,CATLG),DCB=(RECFM=U,LRECL=80,BLKSIZE=1200),
//         UNIT=uuuu,
//         VOL=SER=zzzzzz

Creating Program Tables

During stage I execution, SIP accesses member SPPGML of ACP.SIPGEN.RELvv to determine which programs and versions must be assembled. This member already exists and contains all released programs including most of those created by SIP skeletons.

The program tables created by SIP using SPPGML are divided into separate groups:

In addition to the program name, each entry may contain a version number, if applicable.

Control Program (CP) Table

The CP table contains names and, where applicable, version numbers of all the CSECTs that comprise the control program. Each item in this table identifies a member which may consist of one or more copy cards for a specific CSECT. A copy card is an assembly control statement that contains a segment name. During program assembly, these statements will cause the appropriate segment to be assembled according to the sequence in which they appear. Copy cards are used when a CSECT is too large or complex to be called individually.

The user may not modify the CP table except to change a CSECT's version number when it is being replaced by a user-modified CSECT. In such cases, the user CSECT must be installed to the ACP.SRCE.CP.RELvv library for that release before executing SIP stage II.

Dynamic Link Library (DLL) Load Module Table

The DLL load module table contains all the load module names for DLLs with their associated version numbers. An entry exists in the ACP.LINK.RELvv data set for each load module name. For each entry in the DLL list that IBM ships, there will be a build script entry in the ACP.CSRCE.RT.RELvv data set.

Keypoint (KP) Table

The KP table contains all keypoints, with version numbers, that must be in the system. These keypoints (except for CTK1, CTK2, CTK3, CTK4, and CTK9) initially exist as SIP skeletons in data set ACP.SIPGEN.RELvv. A skeleton is an image of the actual unit enclosed in quotes in a punch statement and can have specific values substituted. These skeletons are converted to source code and assembled during SIP stage II. Refer to each skeleton macro listing commentary for specific information on a particular SIP skeleton.

All names in the KP table, except general file keypoints, are 4 characters plus a 2-character version number. General file keypoints (CTKA and CTKV) are identified by general file version number GF.

The KP table must not be modified because of SIP's use of skeletons to create keypoint source code. However, any user keypoints can be added to TPF by placing them into the UR table.

Offline (OL) Table

The OL table contains names and version numbers for all programs that will be executed in offline mode and are part of the released ACP.SRCE.OL.RELvv and ACP.CSRCE.OL.RELvv libraries. No changes can be made to the released OL table except to change program version numbers for user-modified programs or change the object code designation. In addition, the source code for all user-modified programs must be installed onto the ACP.SRCE.OL.RELvv and ACP.CSRCE.OL.RELvv libraries for that release before executing SIP stage II. Any user-developed offline programs must be assembled and link-edited without using SIP.

Real-Time, Real-Time Special, and User Real-Time Tables

The real-time (RT) and real-time special (RTS) tables contain all system-controlled, ECB-dependent real-time program names with their associated version numbers, which are part of the released ACP.SRCE.RT.RELvv and ACP.CSRCE.RT.RELvv libraries. All program names are 6 characters long with the first 4 characters comprising the segment name, and the last 2 characters being the version number. Any user real-time program may be added to the user real-time (UR) table. User real-time programs will be processed in the same way as system real-time programs. If you want to replace a released program with your own version, just change the released version number to your own version number.

The entries for BAL programs that are called by DLMs are updated with STUB=YES, which means that the object name is added to the stub table (the ISB). During SIP stage II, a DLM stub is generated for each name in this list.

User programs will be accessed via GENSIP macro parameter USRCE, which identifies the user source library. The user source library must be a cataloged data set.

C Language Real-Time and User Real-Time Tables

Note:
The C language real-time (CRT) and user real-time (CUR) tables are for TARGET(TPF) only.

The C language real-time (CRT) and user real-time (CUR) tables contain all ECB-dependent C language real-time program names with their associated version numbers, which are part of the released ACP.CSRCE.RT.RELvv libraries. All program names are 6 characters long, with the first 4 characters comprising the segment name and the last 2 characters the version number. Any C language user real-time program may be added to the CUR table. C language user real-time programs will be processed in the same way as system C language real-time programs. If you want to replace a released program with your own version, just change the released version number to your own version number.

The entries for the TARGET(TPF) programs that are called by DLMs are updated with STUB=YES, which means that the object name is added to the stub table (the ISB). During SIP stage II, a DLM stub is generated for each name in this list.

User programs will be accessed via GENSIP macro parameter USRCE, which identifies the user source library. The user source library must be a cataloged data set.

ISO-C Assembler Function Table (ISA)

The ISA table contains all ISO-C assembler function names with their associated version numbers. An entry exists in the ACP.SRCE.RT.RELvv data set for each ISO-C assembler function.

ISO-C Source Table (ISC)

The ISC table contains all ISO-C source file names with their associated version numbers. An entry exists in the ACP.CSRCE.RT.RELvv data set for each ISO-C source file.

ISO-C Link Table (ICL)

The ICL table contains all the load module names (both library and application) with their associated version numbers. An entry exists in the ACP.LINK.RELvv data set for each load module name. For each entry in the ICL table that IBM ships, there will be a build script entry in the ACP.CSRCE.RT.REL.vv data set. ICL entries for DLMs that are called by other DLMS have STUB=YES.

C++ Language Source Table (CPP)

The CPP table contains all the C++ source file names with their associated version numbers. An entry exists in the ACP.CSRCE.RT.RELvv data set for each C++ source file.

Object Code Only (OCO) Table

The OCO table contains segments for which no source code is shipped. SIP will never attempt to assemble or compile a segment designated as OCO. Object code only programs are shipped as part of the TPF released ACP.OBJ.RELvv library. All program names are 6 characters long, with the first 4 characters comprising the segment name and the last 2 characters the version number. Any object code only program may be added to the OCO table.

Notes:

  1. CTKX, BXAX, COSY, CRS0, and CVZD (general file control record), all of which appear in the RTS table, must not be modified because of SIP skeletons, which are used to create the applicable source code.

  2. The assembler language real-time programs are contained on 3 data sets. These data sets are as follows:

    ACP.SRCE.RT1.RELvv
    All real-time programs that contain a letter A or B as the first character of the program name.

    ACP.SRCE.RT2.RELvv
    All real-time programs containing the letter C as the first character of the program name.

    ACP.SRCE.RT3.RELvv
    All other real-time segments.

  3. The C/C++ language source files are contained on the following data sets:

    ACP.CSRCE.RT.RELvv
    All C/C++ language source files. Build scripts and library interface scripts are also included.

    ACP.CHDR.RELvv
    All C/C++ language headers.

  4. The object code only programs are contained on the following data set:

    ACP.OBJ.RELvv
    All object code only programs.
    Note:
    This ACP.OBJ.RELvv data set will eventually contain all the object code needed to construct a TPF system. It is not intended to contain only OCO programs.

Modifying the Program Tables

You may want to modify or add to any of the program tables, subject to the limitation specified for each table. If such a change is desired, update member SPPGML.

SPPGML consists of a series of SPPBLD macro calls. These macro calls consist of a list of program names, a library-type designator, a support function indicator, an indicator to define if the program is available in object code format, and a subsystem designator. The SPPGML macro is important in the SIP process because it provides the basis of selectability in the stage I assembly. A program module defined in SPPGML will be included or excluded from a user's system based on the options selected by the user in the stage I macros. The format of the SPPGML statement is as follows.

cc10     cc17
 
SPPBLD   TYPE,PGM1,PGM2,......,PGMN,FUNC=yyy,OBJ=YES|NO,SS=ssname,OPT=n

Where:

TYPE
This parameter defines the program library designation.

Valid library types are:

DLL
Dynamic link library

RT
Real-time program library

OL
Offline program library

CP
Control program library

KP
Keypoint program library

RTS
Real-time special program library

UR
User real-time program library

CPP
C++ language source code library

CRT
C language real-time program library (TARGET(TPF) only)

CUR
C language user real-time program library (TARGET(TPF) only)

ICL
ISO-C load module library

ISA
ISO-C assembler function library

ISC
ISO-C source library

OCO
Object code only program library.
Note:
Library type RTS is used in the SPPGML and SPPBLD macros. This library type represents special repetitively used real-time programs processed by SIP. This library designation should not be used by user groups.

PGM1-PGMn
The program segment names to be associated with a particular library type.

FUNC=yyy
This parameter defines the Boolean switch usually set on or off by a SIP user macro. YYY specifies a name given that Boolean switch defined in the SIP GLOBAL definition macro, SPGLB. It is this switch that determines if a program or group of programs are included in the program tables. It is from the program tables that SIP gets the programs for assembly, link-edit, or execution. If a function switch is off (equal to 0), SPPBLD does not put the program names into the associated table. If the switch is on (equal to 1), the program names are installed into the associated program table.

STUB=YES|NO
This parameter is added to SPPBLD so that SIP can generate a DLM call stub for any program called by an ISO-C program. The default is NO.

RENT=YES|NO
This parameter is used to specify whether the source code for an ISC-type program is reentrant. The default is NO for type ISC. For type CPP, do one of the following:

An error message occurs if you code RENT=NO for type CPP.

DLL=YES|NO
This parameter is used to specify whether the source code for type ISC is to become part of a dynamic link library (DLL). The default is NO for type ISC. For type CPP, do one of the following:

An error message occurs if you code DLL=NO for type CPP.

OBJ=YES|NO
This parameter defines to SIP whether these C load modules are to be included in the link JCL created by SIP for the stage II process. If the OBJ parameter is coded YES, this informs SIP that the existing preassembled object version of the program is to be used in the link-edit or execution steps and assembly JCL is not required. If NO is specified, assembly JCL will be created in order to assemble the SOURCE module specified. The default value is NO.

Notes:

  1. The OBJ parameter is ignored for OCO-type programs. OCO-type programs are never assembled or compiled.

  2. See the coding of the ASMALL and OBJLIB parameters in GENSIP.

SS=ssname
This parameter defines to SIP the subsystem in which the programs are to be resident. This parameter is only valid in a TPF system containing the multiple database function (MDBF). See SSDEF. For library type CP, the default is BSS. For all other library types, the default is ALL.

OPT=0|1|2
This parameter specifies the optimization level of the program when the TYPE parameter specifies ISC or CPP. The OPT parameter is ignored for all other types. If this parameter is not specified, the default is 2, which means optimization for C and C++ programs.

0
No optimization

1
OPT(1) for C programs; no optimization for C++ programs.

2
OPT(2) for C programs; optimization for C++ programs.

LINK=YES|NO
This parameter indicates whether SIP is to send link-edit JCL for a C load module.

YES
Specifies that SIP is not to generate link-edit JCL in a stage II deck for this C load module. This parameter is ignored if you code LINKALL=YES on the GENSIP macro. This is the default.

NO
Specifies that SIP will generate link-edit JCL in a stage II deck for this C load module.

See GENSIP for more information about the GENSIP macro.

Any of the previous library types can be modified in the SPPGML macro by using the MVS utility, IEBUPDTE, or any corresponding 80-column card image editor.

WTC Support

SPIPML, released on library ACP.SIPGEN.RELvv, is a list of the program components required by a WTC user in addition to those in SPPGML. SPIPML lists all the real-time programs required by the IPARS application. (Offline programs are listed separately in member SPWTC.) The comments made previously concerning modifications to the member names and inclusion of user versions apply equally to member SPIPML.