gtps4m36System Generation

RAMFIL

The RAMFIL statement is used to specify characteristics of fixed, pool and spare records for TPF database storage devices. The FACE Table is created as a direct result of coding this statement. The order of record groups on disk is determined by the sequence of RAMFIL statements coded in SIP stage I. The RAMFIL statement is required and must be coded in ascending sequence of your file layout. It is recommended that you review information about data organization in TPF Concepts and Structures before coding the RAMFIL statement.

Certain fixed file records are required to have RAMFIL statements coded for them. The specific ones depend on the particular support functions to be included in the system. See Table 16 for the required record types.

See Pool File Storage for information about determining the minimum number of pool directories.

Format




Notes:

  1. For the USER parameter a '*' can be coded in place of SSUID, PROCID, and/or ISN to get the desired level of uniqueness. The '*' means all the subsystem user IDs, processor IDs, or I-streams defined. For non-MDBF customers, a '*' or 'BSS' can be coded in place of SSUID when defining processor or I-stream unique records.

RECID
Specify one of the following:

name
Identifies the record type name used to retrieve the record. For example:
RECID=#WAARI.
Note:
Record types that do not start with # will not work with certain TPF messages.

POOL
Indicates that this is a file pool.

POOL6
Indicates that this is a FARF6 file pool.

SPARE
This value reserves space on a volume.

VTOC
This value reserves space on a volume for the volume table of contents (VTOC) data set. The size of the VTOC data set is 1 track. The BASE parameter must be coded when the VTOC parameter is coded. The last valid track location is cylinder 4369, head 0.

RECNO=n
Number (decimal) of records to be allocated for this record type. Must be greater than or equal to 1. If the record type is a vertically allocated record, the RECNO reflects the records reserved on a single module only. See Table 18 for a list of vertical record types.

TYPE=code
Specifies the size and storage device type for records.
Note:
RAMFIL statements for a specific device type must be grouped together.

SSx
Small record residing on DASD Device x (DEVx). x = TPF devices A, B, C or D

LSx
Large record residing on Device x (DEVx). x = TPF devices A, B, C or D

4Sx
4K records residing on Device x (DEVx). x = TPF devices A, B, C or D
Note:
Refer to ONLFIL macro for DASD devices (Device A, Device B, Device C, Device D).

BAND=n
BAND numbers are only used by FARF3.

The parameter specifies one or more 'band' numbers to be assigned to the RECID specified by this RAMFIL statement. Each band number must be specified as a decimal number from 0 to 4095, inclusive. This operand must be coded for all RAMFIL macros with PRIOR=1 that are to have FARF3 addresses generated, except those with RECID=SPARE or POOL. This parameter is not valid when RECID=SPARE or RECID=POOL. This parameter is ignored if STAGE=FARF45 is coded on the UFTFTI statement.

Each band number value specified represents 65 536 records. The band number is used in conjunction with the low order 16 bits of a record number to form a unique fixed file address for a record by the FACE program. By keeping the band numbers for a record type constant from one system generation to the next, the records can be physically relocated without the fixed file FARF3 address changing. Thus embedded file addresses need not be changed.

If a record type requires more than one (1) band number (for example, has more than 65 536 records including lower priorities or expansion beyond 65 536 records is anticipated) the band numbers may be divided and coded as:

 A range 
BAND = (100-102)

 A sublist 
BAND = (100,101,102,77)

 A combination 
BAND = (100-102,77)

The band numbers are used in the order in which they are specified. That is, the first band number is used for record numbers 0-65535, the second band number for record numbers 65536-131071, and so on.

A band number can only be used once for each subsystem user. However, band numbers for each subsystem user are independent of any other subsystem user. Band numbers may be shared by subsystem user unique records only. Band numbers may not be shared by processor and I-stream unique records. Therefore, when defining processor and I-stream uniqueness, it is necessary to select a new band number for each instance of uniqueness.

UFTI4, UFTI5=(uft,fti)
Specifies which uft/fti combination to use for allocating addresses. Each uft/fti combination is specified, in decimal, as an ordered pair. The range for uft is 0 to 63. The range for fti is dependent on the fti length for the given uft. Refer to the UFTFTI macro UFTFTI and UFT/FTI examples UFT/FTI Examples for more information.

The uft/fti combination is used in conjunction with a record number to form a unique FARF address for a record. By keeping the uft/fti combinations constant from one system generation to the next, records can be physically relocated without the FARF addresses changing. Thus, embedded file address need not be changed.

The uft/fti combination (0,0) is illegal, even though the combinations (0,x) and (x,0), where x > 0, are valid.

If a record type requires more than one (1) uft/fti combination, a list of uft/fti combinations can be coded. For example:

UFTI4=((3,12),(5,24),(3,10))

uft/fti combinations are used in the order in which they are specified, and can be used only once. For instance, notice that the uft/fti combinations are unique in the UFTI4 example statement. The uft/fti combinations must also be unique between the UFTI4 and UFTI5 parameters. They must also be unique between RAMFIL statements.

We recommend that the lowest FTIs be used first for each UFT to conserve space in the FACE table.

This parameter may be coded only for PRIOR=1 fixed file records and for the lowest pool ordinal number (PSON) for a given pool type. The UFTI4 parameter is required if the user wants to define a FARF4 address for a given RECID. The UFTI5 parameter is required if the user wants to define a FARF5 address for the RECID.

The user may want to code UFTI5 in a STAGE=FARF34 FACE table (refer to the UFTFTI statement UFTFTI). Although no FARF5 addresses are created, the ability to migrate will be verified by the offline FACE table generation. This means that the user can put UFTI5 parameters their RAMFIL statements and have the offline table generator check it for them, even though no FARF5 addresses are actually generated. By verifying their UFTI5 statements the user can ensure the FARF5 migration path is intact while still laying out the database for FARF34 migration.

The assembler only allows 255 characters to be coded for a sublist parameter. If more than 255 characters, including parentheses and commas, are coded for UFTI4 or UFTI5, the statement will not assemble. Because information from RAMFIL is not needed during SIP stage I assembly, statements that do not assemble can be commented out. You will need to uncomment these statements before the FACE Table Generator reads them.

UFTI6=(uft,fti)
Specifies which uft/fti combination to use for allocating FARF6 addresses. The UFT/FTI combinations coded for UFTI6 are totally independent from the UFT/FTI combinations coded for UFTI4 and UFTI5. Each uft/fti combination is specified, in decimal, as an ordered pair. The range for uft is 1 to 65535. The range for fti depends on the fti length for the given uft. See UFTFTI and UFT/FTI Examples for more information.

The uft/fti combination is used with a record number to form a unique FARF address for a record. By keeping the uft/fti combinations constant from one system generation to the next, records can be physically relocated without the FARF addresses changing. Because of this, embedded file addresses do not need to be changed.

All uft/fti combinations of the form 0,x are illegal.

If a record type requires more than one (1) uft/fti combination, a list of uft/fti combinations can be coded. For example:

UFTI6=((3,12),(5,24),(3,10))

uft/fti combinations are used in the order in which they are specified and can be used only once. For example, notice that the uft/fti combinations are unique in the UFTI6 example statement. They must also be unique between RAMFIL statements.

We recommend that the lowest FTIs be used first for each UFT to conserve space in the FACE table.

This parameter is valid only for the lowest PSON for a 4-K duplicated long-term pool type. The UFTI6 parameter is required if you want to define a FARF6 address. If the UFTI6 parameter is coded, the UFTI4 and UFTI5 parameters cannot be coded.

DUPE
Specify one of the following:

NO
Indicates nonduplicated record-type.
Note:
In a nonduplicated system DUPE=NO should be coded for all record types. In a fully duplicated system DUPE=YES should be coded. Short-term pools must always be specified as DUPE=NO. See Record Duplication for more information.

YES
Indicates that this is a duplicated record.

BASE=address
Specifies the record address (in decimal). The format is the cylinder and head number (cccchh).
Note:
The BASE parameter is required for:
  1. POOL and FARF6 pool records
  2. Whenever the TYPE or DUPE parameter is different from the TYPE or DUPE parameters on the previous RAMFIL
  3. For all vertical records (#CTKX, #CIMRx, #IPLx, #KEYPT).

POLID
Specify one of the following:

LT
Long-term file storage pool.

ST
Short-term file storage pool.

If POLID is set to ST then the DUPE parameter must be NO.

PRIOR=1|n
Priority number for fixed file records spread across several RAMFIL statements (those that will be chained to others according to PRIOR sequence). Each record type uniqueness group must have a PRIOR=1 (specified either explicitly or by default). The default is 1 and represents a prime entry.

The higher number indicates a lower priority.

The PRIOR parameter does not apply to POOL and SPARE records.

Duplicate RECID names must not be specified with duplicate priorities within the same uniqueness group. No gaps may exist in the PRIORs defined for a particular RECID uniqueness group.

Example:

RAMFIL RECID=#FRED,RECNO=20,TYPE=LSA,PRIOR=3.
RAMFIL RECID=#FRED,RECNO=10,TYPE=LSA,PRIOR=2.
RAMFIL RECID=#FRED,RECNO=30,TYPE=LSA,PRIOR=1,BAND=100
RAMFIL RECID=#FRED,RECNO=15,TYPE=LSA,PRIOR=4.

OVERRIDE=NO|YES
PSON in order coding. If YES is specified, a given RAMFIL statement may be coded with a PSON out of order. If NO is specified, each PSON must be greater than the PSON of the previous pool of the same type. The OVERRIDE parameter is used with POOLS only.
Note:
The OVERRIDE parameter is not valid for FARF6 pools. PSONs can be coded in any order for FARF6 pools without coding the OVERRIDE parameter.

DUMPALTMODE
Exposes improperly or unmigrated FARF addresses.

NO
The system will not dump when processing FARF addresses outside the currently selected dispensing mode.

YES
The system will dump when processing a FARF address for this RECID uniqueness group not in the selected FARF dispensing mode.

DUMPALTMODE is only valid on the lowest PSON of each pool type and is not valid on RAMFILs with PRIORs greater than 1.

Note:
DUMPALTMODE is not valid for FARF6 pools.

USER=attribute
An attribute can have one of the following forms:

An attribute defines the Subsystem Users, Processors, and I-streams associated with a fixed record ID.

An asterisk '*' is used to specify all Subsystem Users, Processors, or I-streams not yet specified in prior RAMFIL statements. The '*' may take the place of either or all of the attribute specified previously. Unspecified attributes default to '*'. In other words the default is USER=(*,*,*).

The SSUID must have been specified in the SSUID parameter of SSDEF.

For non-MDBF customers a '*' or 'BSS' can be used when specifying SSUID.

The PROCID must have been specified in the SYSID parameter of CONFIG.

The ISN must take a value between 1 and 8.

Notes:

  1. An SSUID is required, while the PROCID and ISN specifications are optional. If an I-stream (ISN) is not specified, a processor ID (PROCID) should not be provided either. In this case (where SSUID would appear alone within parentheses), the specification is simply coded as USER=ssu, a subsystem user ID as found in the SSDEF macro.

  2. The USER parameter should not be coded for POOL records (RECID=POOL).

  3. The assembler only allows 255 characters to be coded for a sublist parameter. If more than 255 characters, including parentheses and commas, are coded for USER, the statement will not assemble. Because information from RAMFIL is not needed during SIP stage I assembly, statements that do not assemble can be commented out. You will need to uncomment these statements before the FACE Table Generator reads them.

The following are examples of the USER parameter.

  1. USER=WP2 and USER=(WP2,*,*) are functionally equivalent. The record type is unique to SSU WP2 on all processors and I-streams.
  2. USER=(WP1,*,2) the record type is unique to SSU WP1, on all processors, in I-stream 2.
  3. USER=((WP1,*,*),(WP2,*,*),(HPN,B,*),(WP3,D,6)) the record type is unique to SSU WP1 on all processors and I-streams, to SSU WP2 on all processors and I-streams, to SSU HPN on processor 'B' on all I-streams, to SSU WP3 on processor 'D' on I-stream 6.

INUSE=YES|NO
Specifies that a record is in use.

This parameter is only valid on PRIOR=1 fixed file RAMFIL statements.

PSON=0|n
Specifies the first pool database ordinal number to be used for the pool segment being defined.
Note:
This parameter is valid only when RECID=POOL is specified for a DASD device.

The PSON value specified must not overlap any PSON range for the same DASD pool type. This is true even when going from one device type to another. If PSON is not specified, then SIP will compute PSON as follows:

PSON = highest PSON already defined
       for this pool type plus 1
Note:
The PSON must be specified for FARF6 pools.

For STAGE34 database definitions, PSON recognizes only two categories of pool sizes: small and large. For the purposes of calculating the PSON, 381-byte records are considered "small" while both 1055- and 4K-byte records are considered "large." Therefore, for FARF3 database definitions, 1055 and 4K pool segment PSONs may not overlap with each other.

PSONs must be coded in ascending order for FARF3, FARF4, or FARF5 pool types in a stage I deck unless the OVERRIDE parameter is coded. For FARF6 pools, PSONs can be coded in any order without specifying the OVERRIDE parameter.

Although the SIP calculates a default, it is recommended that this parameter be coded. In Stage FARF3/4 large and 4KB pool records share PSONs, but in Stage FARF4/5 they do not share PSONs. This could lead to the PSONs changing for large and 4KB pool records when the stage is changed from FARF3/4 to FARF4/5.

PSEUDO=0|n
Specifies the number of pseudo modules to be used in the allocation of the pool record addresses for the pool segment specified by this RAMFIL statement. Pseudo modules are modules that are not currently present on the online system but may be added in the future for expansion of the DASD pools without having to do a file reorganization. Pseudo records are records contained on pseudo modules. Like pseudo modules, pseudo records are for expansion purposes only. The number of pseudo records is calculated by multiplying the number of pseudo modules for a given record type by the number of records of that type (RECNO).

The value specified for this parameter must be a multiple of 2 (or 0).

Note:
Another method of expanding the online files which does not require the expansion modules to be pre-planned at system generation time is the use of the Data Base Reorganization Program. This program provides for reorganization of both the fixed and pool records. For further information about database reorganization, see the TPF Database Reference.

If a value greater than 0 is specified, the DASD pool directories will be generated to include pool records residing on the pseudo modules. However, the pseudo module pool record addresses will be in a DEACTIVATED state and, therefore, will not be dispensed by the online system until the file pool programs are told to activate the pseudo modules.

Note:
See TPF Operations for information about how to activate pools allocated on the pseudo modules.

The number of pool records for this segment that can be contained on the pseudo modules must be added to the RECNO parameter value to determine the pool ordinal number range for this segment. See the PSON parameter description above. The pool type (duped/nonduped) and device type duplication (nonduped, fully duped or selectively duped) must be considered in determining the number of pseudo pool records.

Note:
If this parameter is specified, the EXTRx parameter of the ONLFIL macro should also be coded to facilitate the physical addition of the pseudo modules to the online system in the future.

OWNER=triplet|ssu
Where a triplet is of the form:
(SSUID,PROCID,ISN)

The triplet defines the owning subsystem user, processor, and I-stream combination. The owner of a record must also be specified as a user of the record. An SSUID is required, while the PROCID and ISN specifications are optional. When SSUID would appear alone in parentheses, the specification is simply coded as OWNER=ssu, a subsystem user ID as found in the SSDEF macro. For non-MDBF customers, a * or BSS can be used for SSUID. Information specified by this parameter is used by Data Base Reorganization and Recoup.

The default is the first triplet specified or implied by the USER parameter.

This parameter is only valid for fixed file records. The owner of a set of pools is the first subsystem user, processor, and I-stream.

LOMOD=literal 1
Literal 1 is the starting relative module number for the pool segment.

The default value is 0.

This parameter is only valid for POOL records (RECID=POOL, RECID=POOL6). The value coded for this parameter cannot exceed the number of prime and pseudo modules in the system.

NOMOD=literal 2
Literal 2 is the number of pool modules to spread this pool segment over starting at the module specified by LOMOD.

The default is the number of prime + pseudo modules.

This parameter is only for POOL records (RECID=POOL). The sum of LOMOD and NOMOD must not exceed the number of prime and pseudo modules.

UCOMDATA=label
The UCOMDATA parameter attaches user data to the Split Chain Header associated with a RECID. This parameter is valid only on RAMFILs with PRIOR=1 or the lowest PSON for a given POOL type. The label must be a valid entry point in the user data, because it becomes a VCON in the FACE table. The VCON is resolved by the MVS linkage editor. The value coded for this parameter must be the same for all PRIOR=1 fixed file records of the same record id (RECID).

The effect of this mechanism is to provide an extension of information associated with a record type. When the record type is accessed, a pointer to the external user data is returned giving a calling program access to that data.

The symbols "CTSD" and "CONK" are reserved and should not be redefined in the external symbol dictionary. This applies to the UFARFx parameters as well.

This parameter is not valid for SPARE records.

UFARF3=label 1
The UFARF3 parameter attaches user data to the FARF3 split(s) generated by the RAMFIL for which it is coded. The label must be a valid entry point in the user data, because it becomes a VCON in the FACE table. The VCON is resolved by the MVS linkage editor.

This parameter is not valid for SPARE records.

UFARF4=label 2
The UFARF4 parameter attaches user data to the FARF4 split(s) generated by the RAMFIL for which it is coded. The label must be a valid entry point in the user data, because it becomes a VCON in the FACE table. The VCON is resolved by the MVS linkage editor.

This parameter is not valid for SPARE records.

UFARF5=label 3
The UFARF5 parameter attaches user data to the FARF5 split(s) generated by the RAMFIL for which it is coded. The label must be a valid entry point in the user data, because it becomes a VCON in the FACE table. The VCON is resolved by the MVS linkage editor.

The effect of the UFARFx parameters is to make user specified information available on an addressing mode basis.

This parameter is not valid for SPARE records.

UFARF6=label 4
The UFARF6 parameter attaches user data to the FARF6 splits generated by the RAMFIL statement for which it is coded. The label must be a valid entry point in the user data because it becomes a VCON in the FACE table. The VCON is resolved by the MVS linkage editor.

The effect of the UFARFx parameters is to make user-specified information available on an addressing mode basis.

This parameter is not valid for SPARE records and is only valid when the UFTI6 parameter is also coded.

EQU=n
The EQU parameter sets the SYSEQC equate value for the RECID to n. This parameter is valid for fixed and pool records. n must be in the range 0...12287. The purpose of this parameter is for compatibility with older databases requiring segments to be assembled against specific SYSEQC values for record IDs. If not specified, a default is chosen.

RESTORE=YES|NO
This parameter is used to indicate whether or not the record type should be restored. The default is YES except for the following record types whose default is NO: #DBRRI, #RSTRI, #KEYPT, #TPLBL, #CIMR1-8, #CTKX, #KBA, #KSA1-8, #PROG1-8, #OLD1-8, #PVR1-8, #XPRG1-8, #RLOG1-8, and #IPL1-4. This parameter is not valid for POOL or SPARE record types and may only be coded on PRIOR=1 RAMFILs. If it is coded on PRIOR=1 RAMFILs, RESTORE must be coded the same for each PRIOR=1 RAMFIL for a particular record type.

DEACTIVATE=NO|YES
This parameter is used to indicate if a pool segment is going to be deactivated. If YES is specified and a pool deactivation is run, these pool addresses will no longer be dispensed by GETFC macro calls but will continue to be decoded. This parameter is only valid for pool addresses.

RAMFIL Parameter Rules

Table 23. RAMFIL Parameter Rules

Parameter Fixed Pool Spare or VTOC
RECID Required Required Required
RECNO Required Required Required
TYPE Required Required Required
DUPE Allowed
See note 2.
Allowed
See note 2.
Allowed
See note 2.
BASE Allowed
See note 1.
Required Allowed
See note 1.
PRIOR Required
See note 2.
Invalid Invalid
PSON Invalid Allowed Invalid
USER Allowed
See note 2.
Invalid Invalid
INUSE PRIOR=1
See note 2.
Invalid Invalid
BAND PRIOR=1
See note 3.
Invalid Invalid
UFTI4 PRIOR=1
See note 3.
Low PSON
See note 3.
Invalid
UFTI5 PRIOR=1
See note 3.
Low PSON
See note 3.
Invalid
UFTI6 Invalid
Low PSON
See note 3.
Invalid
POLID Invalid Allowed
See note 2.
Invalid
PSEUDO Invalid Allowed Invalid
OVERRIDE Invalid Allowed Invalid
DUMPALTMODE PRIOR=1
See note 2.
Low PSON
See note 2.
Invalid
OWNER PRIOR=1
See note 2.
Invalid Invalid
LOMOD Invalid Allowed Invalid
NOMOD Invalid Allowed Invalid
UCOMDATA PRIOR=1
See note 4.
Low PSON Invalid
UFARF3 Allowed Allowed Invalid
UFARF4 Allowed Allowed Invalid
UFARF5 Allowed Allowed Invalid
UFARF6 Invalid Allowed Invalid
EQU Allowed
See note 5.
Allowed
See note 5.
Invalid
RESTORE PRIOR=1
See note 4.
Invalid Invalid
DEACTIVATE Invalid Allowed Invalid
Notes:
  1. A BASE is always allowed but it is required if the RAMFIL it is coded on has a different type, size or duplication from the previous RAMFIL.
  2. Optional unless the default is unacceptable in which case it must be coded.
  3. The parameter is required if you want splits of a the particular address type generated for this RECID.
  4. If the parameter is coded, the value coded on it must match all the same parameter on all the other PRIOR=1 RAMFILs for this RECID.
  5. If coded, the parameter must appear on the first RAMFIL in the stage I deck for the particular RECID or pool type.

Required
The parameter must be coded.

Allowed
The parameter may be coded.

Invalid
The parameter must not be coded.

PRIOR=1
The parameter may only be coded on a RAMFIL with PRIOR=1 coded.

Low PSON
The parameter may only be coded on the lowest PSON for this particular pool type.

Examples

None.

References