Application 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:

• Permanent Master Files allocated to DDNAME MASTER.
• Temporary Master Files allocated to DDNAME HOLDMAST.

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 data set must be referenced in the allocation, not a particular member.

The data set 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 data set.

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 80-byte 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 data set 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 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 and multi-dimensional indexes. 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 data set must be referenced in the allocation, not a particular member.

The data set 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 data set.

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.

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.

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.

In FOCUS, the procedure named PROFILE must be either a member of the data set allocated to the DDNAME FOCEXEC or a separate file allocated to the DDNAME PROFILE. FOCUS checks the data sets 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.

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. This is not required for PDSE Libraries.

Note:

• Do not use the -RUN statement in FOCEXECs in sequential files, as -RUN closes physical sequential files. Thus, after execution, control will return to the beginning of the FOCEXEC instead of the line directly following the -RUN. (For more information on -RUN, see the Developing Applications manual.)
• FOCEXECs in sequential files may not contain system variables or TSO, -TSO,-INCLUDE, -GOTO, or -IF...GOTO statements. In general, a FOCEXEC in a sequential file should not contain any Dialogue Manager statements or variables because unpredictable results may occur.

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

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 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 data set 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.

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.

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

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

Note: If your site has SMS rules that prohibit multi-volume allocations, the SMS rules will be respected.

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

• Use of storage on specific devices or device types.
• Run-time access to these devices.

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, and TSO 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:

• A need for more than 15 extents.
• A need for a new secondary extent (below the 16-extent limit) when enough space is not available on the volume.

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:

• First volume
• Intermediate volumes
• Last volume

The following table describes the multi-volume allocation process:

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

• You can list multiple volume identifiers.
• You can specify the number of units to use and let the system choose the specific volumes. All of the units will be the same type (for example, 3390).

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

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.

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.

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.

FOCUS data sources appear to the operating system as simple sequential data sets with 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.

FOCUS searches for all dynamically loaded programs in two program DDNAMEs, USERLIB and STEPLIB. USERLIB is searched first, if allocated. If the desired program is not found in the USERLIB DDNAME, then the call library, STEPLIB, JOBLIB, link pack area, and linklist are searched.

If FOCUS is running APF Authorized, data sets allocated to USERLIB must be authorized.

USERLIB, if needed, 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. 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.