Accessing Metadata and Procedures

In this section:

Permanent files include metadata and procedures that were either created before the session by another application or remain after the session is over for use by another application.

Search Rules

Unless a file name is fully qualified with the application name, the search sequence is:

  1. Current directory of the agent, which is edatemp/tsnnnnn.
  2. Applications set using APP HOLDMETA for metadata files, and APP HOLDDATA for hold data files.
  3. Applications set in APP PATH (including MVSAPP for z/OS).
  4. The baseapp application.
  5. The EDAHOME/catalog.
  6. For stored procedures only: if the file is not found, the server checks to see if the file was allocated with a FILEDEF or DYNAM command, and if so, tries to execute it.

Example: Search Paths

The following commands follow the search path, starting with the application set by the APP HOLDMETA command: 

APP HOLDMETA APP1

When a procedure is executed, and referred to by a one-part name 

EX ABC

the following is executed 

profile.fex in APP1 application

followed by 

EX APP1/ABC

If the procedure ABC is not found in APP1, the server follows the standard search path for procedures to find and execute it.

Creation Rules for Procedure Files

Unless a file name is fully qualified or redirected to another location using an APP HOLD, APP HOLDMETA, APP HOLDDATA, FILEDEF, or DYNAM command, it is created in the temporary application area of the agent and disappears after the agent is released.

For example, on z/OS if DYNAM allocation for HOLDMAST or HOLDACC is present, the metadata files are created in the corresponding PDSs (for example, for a CREATE SYNONYM or TABLE FILE file with HOLD).

For related information, see Output Redirection Commands.

Locating Master Files and Procedures

How to:

Once your path is set, you can locate Master Files and procedures using the WHENCE command.

Syntax: How to Locate Files

You can issue the WHENCE command to return the fully-qualified path to the first occurrence of a file in your application path. . You can issue the APP WHENCE command to return the name of the first application on your application path in which the file resides. Nested application directories are supported.

To return the location of the first occurrence of a Master File, procedure, or other FOCUS file type on your application path, issue the following command 

WHENCE filename filetype

To return the name of the first application on your application path that contains a Master File, procedure, or other FOCUS file type, issue the following command 

APP WHENCE filename filetype

where:

filename

Is the name of the file you are trying to locate.

filetype

Is the type of file you are trying to locate.

Example: Locating Files

The following command returns the location of the first occurrence of the Excel file named pivot_demo.xlsx on the application path. 

WHENCE pivot_demo xlsx

The output is:

C:\ibi\apps\retail8205\uploads\pivot_demo.xlsx

The following command returns the name of the application that contains the first occurrence of the Excel file named pivot_demo.xlsx on the application path. 

APP WHENCE pivot_demo xlsx

The output is:

APPNAME: retail/uploads

Accessing Existing Data Files

You can allocate existing data files using the following methods:

It is recommended that you use only one method for each allocation.

Creation Rules for Data Files

How to:

For a newly created data file, the location is determined as follows:

  1. An application set by APP HOLDDATA applies to all HOLD files.
  2. For FILEDEF command, one for each data file.
  3. For z/OS, native operating system allocations when supported.

The request that caused the file to be created determines the file DCB parameters, such as record length, record format, and so on.

For related information, see Output Redirection Commands.

Example: Sample Allocations by JCL

The following table contains sample allocations by JCL.

VSAM

 
//VSAM01 DD DISP=SHR, DSN=qualif.DATA.VSAM

This type of allocation requires the szero = y parameter in the edaserve.cfg file to support sharing of BufferPool Zero.

Fixed

 
//FIX01 DD DISP=SHR,DSN=qualif.FIXED.DATA

PDS

 
//MASTER DD DISP=SHR,DSN=qualif.MASTER.DATA

FOCUS

 
//CAR DD DISP=SHR,DSN=qualif.CAR.FOCUS

Example: Sample DYNAM Commands

The following table contains samples of the DYNAM command.

VSAM

 
DYNAM ALLOC FILE QVASM DA qualif.QVSAM.VSAM SHR REUSE

Fixed

 
DYNAM ALLOC FILE FILE1 DA qualif.FILE1.DATA SHR REUSE

PDS

 
DYNAM ALLOC FILE MASTER DA qualif.MASTER.DATA SHR REUSE

FOCUS

 
DYNAM ALLOC FILE CAR DA qualif.CAR.FOCUS SHR REU

Syntax: How to Issue a FILEDEF Command 

FI[LEDEF] filedes DISK app/[appa.../]physfile.ftm

where:

filedes

Is a file designation (ddname).

app/[appa...]

Is an application name. It can be a nested application name.

physfile.ftm

Is a physical file located in the application.

Syntax: How to Issue a FILEDEF Command to Concatenate Files 

FI[LEDEF] concatname DISK [app1/]filename1.ext
FI[LEDEF] name2 DISK [app2/]filename2.ext
...
FI[LEDEF] namen DISK [appn/]filenamen.ext
FI[LEDEF] concatname CONCAT name2 ... namen

where:

concatname

Is the ddname for one of the files and the name for the concatenated files. Use this name in a request. The individual ddnames will not be available once they are used in a FILEDEF CONCAT command.

name2 ... namen

Are ddnames for the files that will be added to the concatenation.

app1 ... appn

Are application names. They can be nested application names.

filename1.ext ...filenamen.ext

Are the physical file names.

Example: Concatenating Files Using FILEDEF

The following request creates three files, file1.ftm, file2.ftm, and file3.ftm.

APP HOLD app1
TABLE FILE WF_RETAIL_LITE
SUM COGS_US REVENUE_US
BY STATE_PROV_NAME
WHERE STATE_PROV_NAME LE 'F'
WHERE COUNTRY_NAME EQ 'United States'
ON TABLE HOLD AS file1 FORMAT ALPHA
END
-RUN
TABLE FILE WF_RETAIL_LITE
SUM COGS_US REVENUE_US
BY STATE_PROV_NAME
WHERE STATE_PROV_NAME GT 'F' AND STATE_PROV_NAME LE 'M'
WHERE COUNTRY_NAME EQ 'United States'
ON TABLE HOLD AS file2  FORMAT ALPHA
END
-RUN
TABLE FILE WF_RETAIL_LITE
SUM COGS_US REVENUE_US
BY STATE_PROV_NAME
WHERE STATE_PROV_NAME GT 'M' 
WHERE COUNTRY_NAME EQ 'United States'
ON TABLE HOLD AS file3  FORMAT ALPHA
END

The following commands concatenate the three files.

FILEDEF FILE1 DISK app1/file1.ftm
FILEDEF FILE2 DISK app1/file2.ftm
FILEDEF FILE3 DISK app1/file3.ftm
FILEDEF FILE1 CONCAT FILE2 FILE3

The following procedure issues a request against the concatenated files.

TABLE FILE FILE1
SUM COGS_US REVENUE_US
BY STATE_PROV_NAME
ON TABLE SET PAGE NOPAGE
ON TABLE SET STYLE *
GRID=OFF, SIZE=8,$
END

The output is shown in the following image.

Syntax: How to Issue a FILEDEF Command for a Native MVS Data Set 

FI filedes DISK "//'NATIVE.MVS.DATASET'"

where:

filedes

Is a file designation.

NATIVE.MVS.DATASET

Is a Native MVS data set. It can contain any number of qualifiers, up to 44 characters long.

Syntax: How to Issue a USE Command

The USE command can be issued instead of an allocation command for FOCUS data sources. The USE command is the only mechanism for accessing files on the sink machine.

Example: Sample USE Commands

The USE command supports renaming of Master Files and concatenation of data sets. The USE command is the only mechanism for accessing files on the sink machine.

Renaming a Master File 

USE
 CAR1 AS CAR
END

Concatenating Master Files

USE
 CAR1 AS CAR
 CAR2 AS CAR
END

Accessing Files on a Sink Machine 

USE
 CAR1 ON FOCSU01
END

Data Set Names

How to:

If a data set name satisfies one of the following conditions, the server assumes that it is an MVS file name:

In all other cases, the name is interpreted as an HFS file name.

Syntax: How to Define a Data Set

The following syntax is supported: 

DATASET=APP1/physfile.ftm
DATASET='qualif.car.data'
DATASET=qualif.car.data

In addition, on z/OS, you can use the following:

GDG files

 
FILENAME=CARGDG,SUFFIX=FOCUS,
DATASET='qualif.CARGDG.FOCUS(0)'

PDS members

 
FILENAME=CARMEMB,SUFFIX=FOCUS,
DATASET=qualif.CARPDS.DATA(CARMEMB)

FOCUS, VSAM, Fixed

 
FILENAME=CAR,SUFFIX=FOCUS,
DATASET=//'qualif.CAR.FOCUS'