Application Files

In this section:

This section describes how FOCUS refers to and searches for your application files, such as Master Files, FOCEXEC files (stored procedures), FOCUS data sources, USERLIB programs, FOCCOMP files, non-FOCUS data sources, and HOLDSTAT files. It also describes how these files interact with one another under TSO, the various specifics regarding how these files are allocated, and their required DCB attributes.

Master Files

Master Files are partitioned data sets that contain Master Files, consisting of parameter lists that describe data sources to FOCUS. There are two types of Master Files:

When FOCUS needs a Master File, it searches for the ddname MASTER. If FOCUS finds that the ddname MASTER is not allocated when a file is referenced, it attempts to allocate the data set 'prefix.MASTER.DATA' to MASTER. If it does not find the member there, FOCUS next searches the ddname HOLDMAST. If it does not find the member in HOLDMAST either, FOCUS prints an error message.

The maximum LRECL for a variable length file is 32756 bytes; for a fixed length file, the maximum length is 32760 bytes. The record format can be fixed or variable. TED can work with files with an LRECL up to 32760.

Typical TSO and batch allocations for a Master File are:

ALLOC F(MASTER) DA(MASTER.DATA) SHR
//MASTER DD DSN=prefix.MASTER.DATA,DISP=SHR

The entire PDS must be referenced in the allocation, not a particular member.

The PDS member names must correspond to the FOCUS names of Master Files. For example, the FOCUS command TABLE FILE CAR requires a member CAR in the Master File PDS.

Several partitioned data sets of FOCUS Master Files can be concatenated under the ddname MASTER, when they have identical LRECL and RECFM attributes. When the concatenation includes a mixture of variable and fixed record formats, the variable format must be listed first. The widest file must be on the top of the concatenation.

Optionally, you can number the records in a Master File in positions 73-80 for fixed block files. In order to use numbers in these positions in RECFM=VB files, the numbers must be preceded by a ‘,$’ comment marker. FOCUS distinguishes between numbered and unnumbered PDS members when the first record is read. If positions 73-80 are numeric, FOCUS assumes the file lines are numbered and only positions 1-72 are significant. However, FOCUS does not verify that the numbers are in ascending order.

To create and maintain Master Files under TSO, use the TED or ISPF editor. You can access the ISPF editor using the IEDIT command in FOCUS. In batch, use the utility programs IEBPTPCH and IEBUPDTE.

Access Files

Access Files for FOCUS data sources are members of partitioned data sets allocated to ddname ACCESS. They are optional except for intelligent partitioning of FOCUS data sources. For information, see the Describing Data manual.

The maximum LRECL for a variable length file is 32756 bytes and for a fixed length file the maximum is 32760. The record format can be fixed or variable. TED can work with files with an LRECL up to 32760.

Typical TSO and batch allocations for an Access File are:

ALLOC F(ACCESS) DA(ACCESS.DATA) SHR
//ACCESS DD DSN=prefix.ACCESS.DATA,DISP=SHR

The entire PDS must be referenced in the allocation, not a particular member.

The PDS member names must correspond to the Master File member names. For example, the FOCUS command TABLE FILE CAR requires a member CAR in the ACCESS file PDS.

When the Master File has been defined with a long member name, the actual member will be an eight-character name created from the initial characters of the long member name and a unique sequence of characters. For information, see the Describing Data manual.

FOCEXEC or Maintain Files

How to:

All FOCUS procedures can be stored in one or more partitioned data sets allocated to ddname FOCEXEC. The names of the procedures correspond to the member names. Maintain procedures can be allocated to ddname Maintain. For more information, see Maintaining Databases.

The maximum LRECL for a variable length file is 32756 bytes and for a fixed length file the maximum is 32760. The record format can be fixed or variable. TED can work with files with an LRECL up to 32760. The line numbering conventions for Master Files apply to FOCEXEC files as well (see Master Files).

You can use the TED editor to create FOCEXECs. However, the DCB attributes must have been provided before you use TED.

An alternative under TSO for creating FOCEXEC files is the ISPF editor. You can invoke the ISPF editor using the IEDIT command in FOCUS. In batch mode, you can create FOCEXECs with the utility programs IEBPTPCH and IEBUPDTE.

Syntax: How to Execute a Stored Procedure

EXEC procedurename

or

EX procedurename

where:

procedurename

Is the name of the procedure to be executed. This corresponds to the member name.

If you attempt to execute a procedure and no ddname FOCEXEC is found, FOCUS will try to issue the following allocation

ALLOC F(FOCEXEC) DA('prefix.FOCEXEC.DATA') SHR

where:

prefix

Is your TSO PROFILE PREFIX or the FOCUS SET PREFIX= value.

Several partitioned data sets of FOCEXEC procedures may be concatenated under the ddname FOCEXEC.

Example: Executing a Stored Procedure

Sample allocations for the FOCEXEC file in TSO and batch are:

ALLOC F(FOCEXEC) DA(FOCEXEC.DATA) SHR
//FOCEXEC DD DSN=prefix.FOCEXEC.DATA,DISP=SHR

PROFILE FOCEXEC

In TSO, the procedure named PROFILE must be either a member of the PDS allocated to the ddname FOCEXEC or a separate file allocated to the ddname PROFILE. FOCUS checks the PDSs allocated to the ddname FOCEXEC first, and then sequential files allocated to ddname PROFILE. Only the first PROFILE encountered is executed. You may also customize PROFILE procedures and specify these alternatives when you execute FOCUS, as described in Calling FOCUS Under TSO.

FOCEXECs as Sequential Files

If, when executing an EXEC statement, FOCUS does not find the procedure among the members of the data sets allocated to ddname FOCEXEC, FOCUS next checks for a sequential file, with a ddname that matches the procedure name in the EXEC statement. If such a file exists, FOCUS executes this file as the procedure. This feature enables you to store procedures in separate sequential files, which is particularly useful when you are developing and changing procedures frequently. Repeated editing of a PDS member contributes to the need to compress the PDS.

Note:

Example: Allocating FOCEXECs as Sequential Files

Some typical allocations of sequential files used as FOCEXECs are as follows:

ALLOC F(TESTL) DA('TESTL.FOCEXEC.DATA') SHR
//TESTL DD DSN=TESTL.FOCEXEC.DATA,DISP=SHR
//TESTL DD *
.
.
FOCUS statements
/*

StyleSheet Files

All FOCUS StyleSheets can be stored in one or more partitioned data sets allocated to ddname FOCSTYLE. The record format can be fixed length or variable length with LRECL up to 32760 like FOCEXEC, MASTER, or ACCESS. For more information, see Creating Reports.

FOCUS Data Sources

FOCUS data sources contain data written in FOCUS format. See the Describing Data manual for information about maximum file size and partitioning. Each data source is allocated to a ddname that matches the member name of the file's Master File in the PDS allocated to ddname MASTER. For example, if the data source's Master File has the member name LEDGER, then the data source is allocated to ddname LEDGER. You can override this default with the USE command, a DATASET attribute in the Master File, or an Access File. These techniques are explained in the Describing Data manual.

Allocating FOCUS Data Sources

How to:

FOCUS data sources are formatted in 4K pages. XFOCUS data sources are formatted in 16K pages. You can request both primary and secondary allocations. z/OS permits up to 15 extensions of secondary space which you can request in units of tracks, cylinders, or blocks. We strongly recommend that you allocate FOCUS data sources in cylinders, if the file is big enough to justify this.

FOCUS uses the primary space until it is exhausted, and then automatically expands the allocation one extent at a time as more disk storage space is needed for the data.

FOCUS supplies the DCB when you issue the CREATE command. For a FOCUS data source the DCB parameters are RECFM=F, LRECL=4096, and BLKSIZE=4096. For an XFOCUS data source, the LRECL and BLKSIZE are both 16384 (16K). You can use the FOCUS MODIFY and FSCAN commands to maintain these data sources.

If your site does not preallocate FOCUS data sources prior to using them, you can have FOCUS automatically allocate them by issuing the SET FOCALLOC command.

Example: Allocating a FOCUS Data Source

The following example is for a new FOCUS data source:

//CAR DD DSNAME=CAR.FOCUS,UNIT=SYSDA,DISP=(NEW,CTLG),
//VOL=SER=MYVOL,SPACE=(CYL,(5,5))

Syntax: How to Set FOCUS to Automatically Allocate FOCUS Data Sources

SET FOCALLOC = {ON|OFF}

where:

ON

Causes FOCUS to automatically allocate FOCUS data sources with a data set name of prefix.masterfile.FOCUS.

OFF

Indicates that you must allocate your FOCUS data sources. This is the default value.

Multi-Volume Support

How to:

You have the option of allocating new FOCUS data sources, XFOCUS data sources, and FOCUS-created sequential files across multiple volumes.

Many sites prefer to distribute high volume data sources across multiple volumes in order to manage:

You can use this performance tuning technique (also known as data striping) with FOCUS data sources, XFOCUS data sources, and FOCUS-created sequential files in the z/OS batch, TSO, and MSO environments.

The SPACE parameter for allocating any data source can include a primary and a secondary allocation. The primary allocation is the amount of space allocated the first time data is written to the data set. The secondary allocation is the amount of space to be allocated, when necessary, for up to 15 additional extents.

For a single-volume data source, processing terminates with a B37 abend when the system detects either of the following conditions:

FOCUS returns the following message to indicate that one of these conditions has occurred:

(FOC198) FATAL ERROR IN DATABASE I/O. FOCUS TERMINATING CODE: 00000070

You can prevent this type of abnormal termination by allocating multiple volumes to the data source. With multiple volumes, an out of space condition on the first volume causes allocation to start on another volume.

With multiple volumes, the allocation process varies slightly for each of the following:

The following table describes the multi-volume allocation process:

Primary Allocation

The primary allocation is applied to the first volume only. It can consist of the number of extents allowed by z/OS for a primary allocation.

Note: A data source with no secondary space allocation is limited to a single volume.

Secondary Allocation

  1. First volume. As many extents as are available, up to the 16-extent limit, are allocated and filled before continuing to the second volume.
  2. Intermediate volume. Depending on the space available, up to 16-extents are filled before allocation begins on the next volume.
  3. Last volume. Once the need for a number of extents greater than the limit is detected:
    • For a FOCUS data source, processing terminates with the following message:
      (FOC198) FATAL ERROR IN DATABASE I/O. FOCUS TERMINATING CODE 00000070
    • For temporary FOCSORT files, after all volumes and extents are filled, allocation spills to up to 15 additional temporary files, each with 16 extents. The SPACE allocation for each spill file is the same as the SPACE allocation for the original FOCSORT file. For example:
      //FOCSORT DD SPACE

      This allocates a total of 5 + (5*15) = 80 tracks. When the 81st track is needed, another temporary data set is allocated with the parameter SPACE=(TRK,(5,5)). If necessary, this additional step is repeated a total of 15 times yielding a total of 80*16 tracks for FOCSORT.

      If enough space is not available after filling all of the extents of all of the spill files, the FOC198 message is issued and processing terminates. FOCUS places no limits on the size of the FOCSORT file. The limit is determined by the operating system and the amount of space available. You should estimate your space requirements and set your primary and secondary allocations accordingly.

Note: The actual number of extents actually obtained on any volume may be less than 16; however, in most situations 16 will available and used.

 

Syntax: How to Allocate a Multi-Volume Data Source in the z/OS Batch Environment

You have two choices for statically allocating a new multi-volume FOCUS data source, XFOCUS data source, or sequential file.

You can list multiple VOLSER identifiers on the DD card for the multi-volume data source:

//ddname DD DSN=dsname,VOL=SER=(vol1,...,voln),... 

Alternatively, you can ask for multiple units of a specific type

//ddname DD DSN=dsname,UNIT=(type,n),...

where:

ddname

Is the DDNAME associated with the multi-volume data source.

dsname

Is the data set name of the multi-volume data source.

vol1,...,voln

Are the volume identifiers for each of the volumes to use.

type

Is the type of unit to use.

n

Is the number of units.

Allocating a Multi-Volume Data Source in TSO and z/OS FOCUS

How to:

In both TSO and z/OS FOCUS you have two choices for dynamically allocating a multi-volume data source:

Syntax: How to Allocate Specific Volumes in TSO and z/OS FOCUS

To allocate specific volumes for a multi-volume data source, use the following syntax:

In TSO

TSO ALLOC ... VOLUME('vol1,...,voln')... 

In z/OS FOCUS

DYNAM ALLOC ... VOL vol1,...,voln ... 

where:

vol1,...,voln

Are the volume identifiers for the each of the volumes to use.

Syntax: How to Specify the Number of Units in TSO and z/OS FOCUS

To specify the number of volumes for a multi-volume data source and let the system choose the specific volumes, use the following syntax:

In TSO

TSO ALLOC ... UCOUNT('n') UNIT('type') ...

In z/OS FOCUS

DYNAM ALLOC ... UCOUNT n UNIT type ...

where:

n

Is the number of volumes to use.

type

Is the type of unit to use.

Note:
  • UNIT VIO is not supported.
  • The RLSE option of the SPACE parameter is not supported.

Example: Allocating a Data Source to Two Volumes

The following DYNAM command allocates two volumes to a data source called MULTVOL:

DYNAM ALLOC FI MULTVOL DS USER1.FOCTST.MULTVOL TRACK SPACE 4 4 REU -   
 UCOUNT 2 UNIT SYSDA CATALOG

With this allocation, a second volume will be used when the 17th extent is needed.

Syntax: How to Display the Volume Identifiers Allocated to a Multi-Volume Data Source

To see the data set information associated with a specific DDNAME, issue the following command

? TSO DDNAME ddname

where:

ddname

Is the DDNAME allocated to the data set whose volume identifiers you want to see.

Example: Displaying Multi-Volume Data Set Information

The following example shows how to display data set information for DDNAME MULTVOL:

? TSO DDNAME MULTVOL

The following information is returned. Notice that two volume serial identifiers are listed on the VOLSER line:

DDNAME      =  MULTVOL
DSNAME      =  USER1.FOCTST.MULTVOL
DISP        =  NEW
DEVICE      =  DISK
VOLSER      =  MFOC02,MFOC01
DSORG       =  PS
RECFM       =  F
SECONDARY   =     4
ALLOCATION  =  TRACKS
BLKSIZE     =      4096
LRECL       =      4096
TRKTOT      =        92
EXTENTSUSED =        23
BLKSPERTRK  =        12
TRKSPERCYL  =        15
CYLSPERDISK =      2227
BLKSWRITTEN =      1104
FOCUSPAGES  =      1059 
>  >

External Indices for FOCUS Data Sources

An external index is a FOCUS file that contains index, field, and segment information for one or more specified FOCUS data sources. The external index is independent of its associated FOCUS data source and is used to improve retrieval performance.

In z/OS, the external index is automatically allocated as a temporary file when it is created using REBUILD. To create the permanent external index, you must allocate it before you issue the REBUILD command.

SORTOUT is a work file that is used during the process to create an external index. You must allocate the work file with the proper amount of space, minus DCB parameters. To estimate the amount of space, use this formula:

bytes= (field_length + 20) * number_of_occurrences

MDIs for FOCUS Data Sources

An MDI is a separate multi-field index file for one or more FOCUS databases. The MDI is independent of its associated FOCUS database and is used to improve retrieval performance.

To create the MDI, you must allocate it before issuing the REBUILD command. The DCB attributes are RECFM=F, LRECL=4096, BLKSIXE=4096.

Disposition of FOCUS Data Sources

Existing FOCUS data sources can always be allocated as SHR by both TSO users and background jobs, even when being modified. Concurrent destructive updates are prevented by FOCUS itself. FOCUS reserves exclusive use of the data source, for update purposes, for the duration of the MODIFY command. At the conclusion of the MODIFY, the TSO user or batch job that had possession of the data source relinquishes control, making the data source available to the other users.

While only one TSO user or batch job is allowed to update the data source, multiple users may have the data source open concurrently for read-only purposes. This scheme offers the same protection as exclusive allocation (DISP=OLD), but it is more flexible, because with DISP=OLD, the data source is reserved for the duration of the allocation (which, for a batch job, is the entire time from initiation to termination).

If a TSO user attempts to modify a FOCUS data source currently being modified by another user or batch job, or if the data source is controlled by a FOCUS database server (sink machine), the result is a message stating that the data source is in use elsewhere and the MODIFY command flushes to the END statement allowing you to perform other tasks. On the other hand, if a batch job encounters the same situation, it will wait until the data source is free (that is, until the MODIFY currently in control ends or the FOCUS database server is terminated).

When TABLE and TABLEF commands are run for the purpose of locating cross-referenced segments (segment types KU and KM), you must allocate the data source with DISP=OLD or NEW. This allows for their addresses to be written into the data source from which they are being cross-referenced. This process, called pointer resolution, does not take place if the disposition of the data source is SHR or if the data source resides on a FOCUS database server.

Database Security: ENCRYPT, DECRYPT and RESTRICT

How to:

Since the restriction information for a FOCUS data source is stored in its Master File, you will want to encrypt the Master File in order to prevent users from examining the restriction rules. Only the Database Administrator can encrypt a Master File. If you wish to change restrictions, the process can be reversed using the DECRYPT command to restore the Master File to a readable form. You can add security limitations to existing data sources using the RESTRICT command.

Syntax: How to ENCRYPT a FOCUS File

ENCRYPT FILE membername {MASTER|FOCEXEC}

where:

membername

Is the name of the member in the PDS to be encrypted.

Example: Encrypting a FOCUS File

The following command encrypts member EMPLOYEE of the PDS allocated to ddname MASTER:

ENCRYPT FILE EMPLOYEE

Syntax: How to DECRYPT a FOCUS File

DECRYPT FILE membername {MASTER|FOCEXEC}

where:

membername

Is the name of the member of the PDS to be decrypted.

Syntax: How to RESTRICT a FOCUS File

RESTRICT
ddname1 
ddname2 
.
.
.
END

where:

ddname1, ddname2

Are the ddnames allocated to the files that will be restricted.

Example: Restricting a FOCUS File

The following restricts the files allocated to ddnames CAR and EMPLOYEE:

RESTRICT
CAR
EMPLOYEE
END

FOCUS Data Sources and IBM Utility Programs

Although random access techniques (BDAM) are used with FOCUS data sources, the files appear to the operating system as simple sequential data sets with a fixed-length, unblocked 4096-byte records. Thus, FOCUS data sources can be processed by all of the common IBM data set utility programs (such as IEBGENER and the TSO COPY command). Every IBM utility program that works on sequential files (DSORG=PS) may be used, so you can freely move, back up, copy, and store FOCUS data sources in whatever way your installation chooses.

USERLIB

FOCUS searches for all dynamically loaded programs in two program libraries: USERLIB and STEPLIB. USERLIB is searched first, if allocated. If the desired program is not found in the USERLIB library, then the call library, STEPLIB, JOBLIB, link pack area, and linklist are searched, in that order. This search logic is followed in all cases, whether the program to be loaded is an Interface module, a user-written exit from a computation expression, or a DATA VIA module.

Libraries allocated to USERLIB must be authorized. Unauthorized libraries should be allocated to STEPLIB.

USERLIB, if present, must be allocated before its first use. This can be done in the logon procedure, through an ALLOCATE command, from within FOCUS, or without. However, if issued from within FOCUS, it cannot be reallocated after the first use. The allocation remains in effect for the remainder of the FOCUS session.

If the special function library called myprogram.load is needed, it should be allocated to ddname USERLIB or FUSELIB. For example:

ALLOC F(USERLIB) DA('myprogram.load') SHR

Any arbitrary library is allocated as USERLIB:

ALLOC F(USERLIB) DA('USER.LIBRARY.load') SHR

These libraries can be concatenated as follows:

ALLOC F(USERLIB) DA('myprogram.load USER.LIBRARY.load') SHR

Note: Within FOCUS, the TSO ALLOCATE or DYNAM ALLOCATE command must be used.

FOCCOMP Files

How to:

The FOCCOMP file contains the output from the COMPILE command, and is used to run the compiled MODIFY procedure.

When you allocate this file, do not specify DCB attributes for this PDS. FOCUS chooses the most efficient block size for the disk type being used.

Note: You cannot use concatenated FOCCOMP data sets when compiling MODIFY procedures.

Syntax: How to Create a FOCCOMP File

COMPILE focexecname

where:

focexecname

Is the name of the FOCEXEC.


Information Builders