gtpm1m1bTPF V4R1 Migration Guide: 3.1 to 4.1

Program Allocation Process

The program allocation process was changed substantially in the TPF 4.1 system:

Allocating Programs, Transfer Vectors, and Pools

There are significant changes to the system allocator (SALO) process in the TPF 4.1 system:

There can be up to 16 input decks. IBM provides one input deck, which is the IBMPAL input deck. You can concatenate up to 15 input decks of your own. Do not add allocator statements to the IBMPAL input deck because the order of the programs in the decks determines their ordinal number (also known as the program record number (PRN)) in the 4 KB fixed file record area. However, you may need to modify the allocator statements to meet your needs. All programs are allocated as 4 KB.

You do not need to put all of the required core resident programs at the front of the allocator decks because residency is specified on the allocator statement itself, rather than being determined by the position of the allocator statement.

You need to specify the names of the input decks and the data set that contains them on the new INDSN macro using these parameters.

SALDSN
The name of the input data set that contains all of your input decks (as members) for the system allocator.

SALMEM
A sublist of up to 15 deck (member) names. These decks, along with system required decks, are used as input to the system allocator.

Each SALO input deck consists of one or more statements in one of the formats described in the next section. You must code all statements, except comments, in uppercase.

Specifying the Addressing Mode

When you want a block of programs to run in a particular addressing mode (24-bit addressing mode or 31-bit addressing mode) without specifying this on each individual input statement, you can use the MODE statement. This statement provides a default mode setting for all subsequent program statements in the input decks.

The format of the MODE statement follows:




MODE=24BIT|31BIT

where 24BIT is the default.

Notes:

  1. All programs written in IBM C language must be allocated in 31-bit addressing mode. This allows them to call heap storage functions, which return 31-bit addresses.

  2. The FACE, SIGT, RIAT, and SNA tables are now above 16 MB. All programs that manipulate these tables or reference the FC0TB, SI0GT, and DCTRIT data macros must be allocated as 31-bit addressing mode.

Allocating Programs

All program records are 4 KB. The order in which the programs appear in the input decks determines their program record numbers (PRNs). Every program allocation statement is allocated as a 4 KB block.

The format of the input statements for allocating file resident and main storage resident or core resident programs follows:




prog,FR|CR [,CLASS=SHARED|COMMON|UNPROT|ISUNIQ|PRIVATE] [,MODE=24BIT|31BIT]
[,OPTIONS=(KEY0,MONTC,RESTRICT,CMB,xxx)][,SS=ALL|EXC|ssname]
[, FUNC=1|0|fsname]
[, PRELOAD ]

Where:

prog
The 4-character program name that is being allocated. The program name must be four characters long and the first character must be alphabetic.

FR|CR
Indicates whether the program is to be file resident (FR), main storage resident, or core resident (CR). FR replaces the MR used in previous releases.

CLASS=
Defines the residency characteristics of the program. Programs can reside in protected or unprotected storage, be I-stream shared, I-stream unique, or ECB-unique. Table 41 summarizes the attributes associated with the different classes.
Note:
The distinction between shared and I-stream shared. The SHARED class refers to ECBs sharing the same copy of a program, which is the default. COMMON refers to ECBs sharing a copy of the program and seeing it at a common address.

Self-modifying programs must be allocated as unprotected, which causes the demand counter to remain as part of the 8-byte program header. The demand counter for protected programs is in the program allocation table (PAT).

Note:
Core resident programs must have CLASS values of SHARED or COMMON.

SHARED
Indicates that all ECBs use the same copy of the program, but only those ECBs currently using the program can view it. In addition, all ECBs using the program can potentially access the program at different ECB virtual addresses. The program resided in page-protected memory and key-protected memory. The demand counter for shared programs is located

in the PAT entry of the program.

The default is SHARED.

COMMON
Indicates that all ECBs use the same copy of the program and access the program at the same address. The program resides in key-protected storage. The demand counter for a common program is located in the PAT entry of the program.

UNPROT
Indicates that this is a self-modifying I-stream shared program. All ECBs use the same copy of the program and access the program at the same address. The program resides in unprotected storage. The demand counter for an unprotected program is in the 8-byte program header.

ISUNIQ
Indicates that this is a self-modifying I-stream unique program. All ECBs on the same I-stream use the same copy of the program and access the program at the same address. All copies of the program reside in unprotected storage. The demand counter for an I-stream unique program is in the 8-byte program header.

PRIVATE
Indicates that this is a private program to be loaded to a unique unprotected working storage block each time it is entered. Private programs do not have a demand counter.

The default is SHARED.

Table 41 summarizes the use of the CLASS values for file resident programs.

Table 41. Summary of CLASS Values for File Resident Programs

  I-Stream Shared I-Stream Unique ECB Unique Same Address Protected Un-Protected
SHARED X       X  
COMMON X     X X  
UNPROT X     X   X
ISUNIQ   X   X   X
PRIVATE     X     X

MODE=24BIT|31BIT
The addressing mode in which the program is entered. This parameter overrides any preceding MODE statement for this program. All programs written in IBM C language must be allocated in 31-bit mode.

OPTIONS=
One or more of the following macro authorization options (separated by commas).

KEY0
Authorization specifies that the E-type program is allowed to issue a CINFC W, which allows the program to store into protected storage.

MONTC
Specifies that the E-type program is allowed to issue a MONTC macro, which allows the program to store into protected storage as well as process privileged instructions until the program issues a LMONC macro.

RESTRICT
Specifies that the program is allowed to issue macros that are restricted for other reasons.

CMB
Specifies that the program can issue the GETCC macro to get common blocks.

xxx
Specifies a user-defined authorization. You can define up to eight of these. See Adding Your Own Authorization Bits for more information.

See Issuing Macros that Require Authorization for a list of macros that require one or more of these authorizations by the calling E-type program.

SS=
A valid subsystem name as declared in the SIP Stage I SSDEF macro.

ALL
Indicates that the program should be allocated in all subsystems.

EXC
Indicates that the program should be allocated in all subsystems except the BSS.

ssname
A valid subsystem name as declared in the SIP Stage I SSDEF macro.

The default is ALL.

FUNC=
A function switch.

1
Specifies that the program allocated by this statement is placed in both the system allocator (SAL) table and the program allocation table (PAT).

0
Specifies that this program is a dummy and is put only in the system allocator (SAL) table.

fsname
A valid switch name taken from the SIP-created IBM C language header file c$idfunc.h. See Adding Your Own Function Switches for more information.

The default is 1.

PRELOAD
Guarantees a core resident program will be resident in the CRPA before it is called for the first time. These programs are loaded synchronously at the beginning of restart.

All other core resident programs will be loaded by one of two methods:

The preferred method can be specified during SIP Stage 1 or by entering the ZSYSG ALTER command.

Be sure to define the core resident program area (CRPA) large enough to hold all the core resident programs. Failure to do so may cause the TPF 4.1 system to go into input list shutdown due to a depletion of blocks.

Allocating Transfer Vectors

A transfer vector is the label name given to an entry point into a program. The program in which the entry point is located is called the parent. The parent can have multiple entry points (transfer vectors) within it. An allocation statement in a parent program must precede all its transfer vector's allocation statements. A transfer vector has the same allocation attributes as its parent. Each transfer vector uses 4 KB of DASD.

The format of the input statements for allocating transfer vectors follows:




prog,TV,parent,tv#

Where:

prog
The 4-character transfer vector name that is being allocated. The first character must be alphabetic.

TV
Indicates that this is a transfer vector statement.

parent
The 4-character program name this transfer vector is located in. The parent cannot be a transfer vector.

tv#
The transfer vector number for prog, which must be a decimal number in the range 0 to 1023.

Allocating Spare Program Slots

Spare statements interspersed throughout the program allocation table (PAT) hold resources so that programs can be placed in these positions at a later time. This allows you to add and delete programs without requiring a full load. Any programs you add without using spares must be added after the last entry in the last input deck. If programs are added in the middle, a full load must be done.

The format of the input statements for allocating spare program slots follows:




SPARE

Where:

SPARE
Indicates that this is a spare statement.

Defining Pools

The format of the input statements for defining pools follows:




poolsym,TYPE=POOL,VALUE=svc

Where:

poolsym
The 3-character GFS ID to be expanded. The first two characters are the record ID and the third character is the record size attribute (L for large records or S for small records).

svc
A 3-byte hexadecimal SVC interrupt code. Valid codes include:

 0ABC nn
SLT (small, long-term)

 OABE nn
SST (small, short-term)

 0AC0 nn
SDP (small, duplicated)

 0AC2 nn
LLT (large, long-term)

 0AC4 nn
LST (large, short-term)

 OAC6 nn
LDP (large, duplicated)

Where nn is:

00
ratio dispensing option

04
DASD Device A

08
DASD Device B

0C
DASD Device C

10
DASD Device D

Adding Your Own Authorization Bits

In the TPF 4.1 system, you can authorize programs for certain privileges, such as issuing:

You may want to grant (or deny) other privileges to programs, and you can do this by defining up to eight of your own user authorization bits.

The bits are defined in the c$idsalo.h IBM C language header file. To add your own bits, edit this file and add your own authorization names and their corresponding bit values.

Adding Your Own Function Switches

Function switches determine whether a program is allocated normally or as a dummy program.

To Add Your Own Function Switches

  1. Update the SIP SKFUNC skeleton. Add your new switch in four places:
    1. In the list of switches in the prolog section (comments) of the macro, along with a description of the switch.
    2. In the section where global variables are defined, for example:
            GBLB &NEWFUNC
      
    3. In the section containing SETB instructions, for example:
            &NEWFUNC    SETB    (&SBaaaa AND &SBbbbb)
      
      (where &SBaaaa and &SBbbbb are defined function switches).
    4. In the final section that punches out the IBM C language header file, before the EOFL statement, for example:
            PUNCH '             "NEWFUNC",&NEWFUNC,'
      
  2. Code your new function switch name on the FUNC parameter of the program allocation statement.
  3. Code EXPRS=S on the SIP GENSIP macro to generate the c$idfunc.h IBM C language header file.
  4. Rerun SIP Stage I.
  5. Run the JCL generated by step 4.

When adding a new function switch, avoid using names beginning with &SB. This naming convention is reserved for IBM use.