Application Metadata Commands and Catalog Metadata

In this section:

Developers may want to write applications that check application metadata and decide a course of action. For example, they may want to check the existence of a file or a file date, and decide on the need for another step, such as recreation of the file. There are multiple ways to accomplish a simple check for file existence or some other attribute, that have evolved over the release history of the product. However, some of these methods have limitations. A good example of this is the STATE command, which uses a native path name for UNIX. This type of path name would not match a Windows file path and, therefore, would require IF THEN ELSE or GOTO logic to issue the correct version of the command for the operating environment, that might be quite cumbersome, depending on how often it is needed.

To solve part of this problem, commands such as STATE, FILEDEF, and DYNAM have been extended to support APP names (that is, issue APP MAP then use STATE mymap/myproc.fex). To deal with more complex issues, such as retrieving a list of available applications (APP names) and files within a particular application, a series of APP commands were developed (APP LIST and APP QUERY). However, as features such as nested applications (sub-directories) were implemented, it became apparent that a much more extended ecosystem for accessing application metadata was needed.

To satisfy this need for extended information, various internal tables were extended or created. Today the catalog/sysapps table is the primary method for accessing application metadata using standard TABLE or SELECT syntax. This is what is used in most internal applications. That is not to say that the prior methods are no longer supported. At times they can provide quick and simple coding for a specific need, but they have limitations (as noted). More complex situations require the use of the newer methods to access information. Additionally, tables such as catalog/systables and catalog/syscolum can provide additional information that is table specific, such as what DBMS a table is using and the data specification of particular columns, but they are beyond the scope of this section. It should also be noted that the newer methods occasionally overlap on how to accomplish a task. For example, a number of the catalog/sys* tables can be used to answer the question of whether a file exists. However, the tables differ from each other in the more detailed information, such as physical or application locations and attributes.

Retrieving Basic Information

In this section:

The following commands return basic information about files and applications.

STATE

How to:

The STATE command lets you check for the existence of a file. The file reference you supply can be the full path native operating system file name, or a file name prefaced with an APP name. This section only described the use of APP-name prefaced files. When an APP name is used, it does not matter if the name was natively created under the APPROOT location of the server or as an APP MAP name.

If the file does not exist, the STATE command displays a message to that effect. After issuing the STATE command, the &RETCODE system variable contains the value zero (0) if the file exists, or a non-zero value if the file does not exist.

Syntax: How to Check File Existence

STATE appname/filename.filetype -TYPE RETCODE &RETCODE

where:

appname

Is the application under which the file is stored.

filename

Is the name of the file.

filetype

Is the file type or extension of the file.

If the file exists, the &RETCODE value will be 0 (zero). Otherwise, it will be non-zero and can be used to further direct the logic of the application, typically in a -SET or a -IF command. The STATE command will also output a not found message. To suppress this message, use the SET TRMOUT={OFF|ON} command.

For example, the following STATE command checks the existence of the file myproc.fex in the baseapp application. The STATE command displays a message if the file does not exist. The -TYPE command displays the value zero (0) if the file exists or the value -1 if the file does not exist.

STATE baseapp/myproc.fex
-TYPE RETCODE &RETCODE
Example: Checking the Existence of a File With the STATE Command

The following partial example suppresses the message returned by the STATE command, issues the STATE command to check if the file myproc.fex exists in the baseapp application, checks the return code, and creates the file if it does not exist, before continuing with the next step in the application. If the file does exist, the code immediately transfers to the next step in the application, (-RESUME label):

SET TRMOUT=OFF
STATE baseapp/myproc.fex
SET TRMOUT=ON
-IF &RETCODE EQ 0 THEN GOTO RESUME;
...
* Some code to create the file goes here
...
-RESUME

APP LIST

How to:

The APP LIST command alphabetically lists the applications available under the application root, APPROOT, or under an APP MAPped location. It does not care if the APP is on the current application map or not, as it is a raw list of available applications.

Syntax: How to List the Applications in APPROOT

APP LIST [HOLD]

If the HOLD option is used, the output is written to a temporary file called focappl.ftm, (FOCAPPL on PDS Deployment), which can, in turn, be used in a request to drive a report or take an action using the catalog/focappl Master File.

Limitations:

  • APP LIST does not display nested application names.
  • On operating systems that use case sensitive file names (such as UNIX), uppercase physical directory names are not valid (so are not returned by APP LIST). APP names are case insensitive, but they are created on disk as lowercase, which may in turn be upper-cased by the native operating system (that is, PDS uppercase file names). However, APP LIST returns them in lowercase, to be homogenous across operating systems.
Example: Using APP LIST to List and Work with Applications

The following request lists applications

APP LIST

The APP LIST output is:

BEGIN-APP-LIST
15/02/2000  13.36.38   baseapp
15/02/2000  13.36.38   ggdemo
15/02/2000  13.36.38   ncp
15/02/2000  13.36.38   template
END-APP-LIST

The following request lists applications that have been stored using the HOLD option

APP LIST HOLD
SQL SELECT DATE, TIME, APPNAME FROM FOCAPPL;
END

The APP LIST output is:

DATE        TIME      APPNAME
----        ----      -------
15/02/2000  13.36.38   baseapp
15/02/2000  13.36.38   ggdemo
15/02/2000  13.36.38   ncp
15/02/2000  13.36.38   template

The following practical example of using the APP LIST HOLD command issues a TABLE request against the HOLD file to check if any files exist in the application myapp. If no lines are returned, the application does not exist, so it is created, and the application continues. Otherwise, the application continues without creating the application.

APP LIST HOLD	
TABLE FILE FOCAPPL
PRINT * ON TABLE HOLD WHERE APPNAME = 'myapp'
END
-IF &LINES GT 0 THEN GOTO RESUME
APP CREATE myapp
-RESUME

APP QUERY

How to:

The APP QUERY command lists files within a given application. Applications and specific nested applications can be queried.

Syntax: How to List Components

APP QUERY app1[/app1a...]  [app2[/app2a]...] ...
  [appn[/appna]] [HOLD]

where:

app1[/app1a...appn[/appna]

Are application names. They can be nested application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and continue more application names on the next line.

If the HOLD option is used, the output is written to a temporary file called focappq.ftm (FOCAPPQ on PDS Deployment), which can, in turn, be used in a request to drive a report or take an action using the catalog/focappq Master File.

Limitations: All files within an APP are listed. On systems like UNIX, this may include files of any case, so files such as MYPROC.FEX and myproc.fex may appear in a listing, but only the lowercase version would be accessed in a request.

Example: Listing Application Files

The following request lists application files.

APP QUERY abc

The APP QUERY output is:

BEGIN-APP-QUERY: abc
24/10/2014 21.38.28        4 F myproc1.fex
24/10/2014 21.38.35        4 F myproc1.fex
24/10/2014 21.37.49        4 F myapp1
24/10/2014 21.32.36        0 D myapp2
END-APP-QUERY

The following request lists files that have been stored using the HOLD option.

APP QUERY ABC HOLD	
SQL SELECT DATE, TIME, GMTTIME, SIZE, OTYPE, FILENAME, APPNAME FROM FOCAPPQ ;
END

The APP QUERY output is:

DATE        TIME      GMTTIME     SIZE  OTYPE FILENAME     APPNAME
----        ----      -------     ----  ----- --------     -------
24/10/2014  21.38.28  1414201108  4     F     myproc1.fex  abc
24/10/2014  21.38.35  1414201115  4     F     myproc2.fex  abc
24/10/2014  21.37.49  1414201069  4     D     myapp1       abc
24/10/2014  21.32.36  1414200756  0     D     myapp2       abc

Note that APP QUERY … HOLD returns a slightly extended type of information. Whitespace has selectively been removed from the above output for readability (the FILENAME column is actually 70 characters wide).

The following practical example of using the APP QUERY HOLD command checks the existence of the file myproc1.fex in application abc. If the file does not exist, the procedure exits. If the file does exist, the procedure continues.

APP QUERY abc HOLD
TABLE FILE FOCAPPQ
PRINT * ON TABLE HOLD 
WHERE APPNAME = 'abc'
WHERE FILENAME = 'myproc1.fex'
END
-IF &LINES GT 0 THEN GOTO RESUME
-TYPE Procedure Not Found ... exiting!
-EXIT
-RESUME

Retrieving Extended Catalog Information

In this section:

This section provides basic information about querying the server catalogs.

catalog/sysapps

The catalog/sysapps table contains metadata for physical objects on path.

This section only touches on basic uses typically needed by a developer. The Master File on disk robustly describes more attributes than are described here. You can directly study the Master File in order to understand other uses. The catalog/sys* group of files are subject to change (and are usually upwardly compatible). You should never write applications that have specific dependencies (typically on object size), which tend to cause upward compatibility issues.

Example: Listing Files in an APP

The following request lists the application name, application location, file names, and file extensions in the application named abc.

TABLE FILE SYSAPPS
PRINT APPNAME APPLOC FNAME FEXT
WHERE APPNAME EQ 'abc' ;
END

The output (with whitespace selectively removed for readability) is:

APPNAME     APPLOC                    FNAME        FEXT
-------     ------                    -----        ----
abc         /usr/wf/ibi/apps/abc      myproc1      fex
abc         /usr/wf/ibi/apps/abc      myproc2      fex

The following practical example of using the SYSAPPS table to check file existence checks the existence of the file myproc1.fex in the application abc. If it does not exist, the procedure exits. If the file does exist, the procedure transfers to the next step in order to continue:

TABLE FILE SYSAPPS	
PRINT * ON TABLE HOLD 
WHERE APPNAME = 'abc' ;
WHERE FNAME =  'myproc1' ;
WHERE FEXT = 'fex' ;
END
-IF &LINES GT 0 THEN GOTO RESUME
-TYPE Procedure Not Found ... exiting!
-EXIT
-RESUME

catalog/sysfiles

The catalog/sysapps table contains metadata for app name objects on a path for a select object type. The default is for file type MASTER (Master Files), but is settable for other types. Unless limited in some way, all objects (of the selected type) are displayed.

This section only touches on basic uses typically needed by a developer. The Master File on disk robustly describes more attributes than are described here. You can directly study it in order to understand other uses. The catalog/sys* group of files are subject to change (and are usually upwardly compatible). You should never write applications that have specific dependencies (typically on object size), which tend to cause upward compatibility issues.

Example: Listing APP MASTER Objects

The following request lists file names, file names with their application paths, and extensions of files with file type MASTER (the default):

TABLE FILE SYSFILES
PRINT FILENAME LGNAME PHNAME EXTENSION
END

The output (with some records and whitespace selectively removed for readability) is:

FILENAME         LGNAME    PHNAME                          EXTENSION
--------         ------    ------                          ---------
...
mydata           MASTER    baseapp/mydata.mas              mas
mdschema         MASTER    _edahome/catalog/mdschema.mas   mas 

Example: Listing APP FOCEXEC Objects

The following request sets the file type to FOCEXEC and then prints the file names, file names with their application paths, and extensions of files with file type FOCEXEC:

SQL FMI SET SYSFILES FOCEXEC
TABLE FILE SYSFILES
PRINT FILENAME LGNAME PHNAME EXTENSION
END

The output (with some records and whitespace selectively removed for readability) is:

FILENAME         LGNAME    PHNAME                          EXTENSION
--------         ------    ------                          ---------
...
myproc1          FOCEXEC   baseapp/myproc1                 fex
myproc2          FOCEXEC   baseapp/myproc2                 fex
...

Note: The value for LGNAME will switch to DEFAULT if the data is limited and only one object returns.

A valid value for the SQL FMI SET SYSFILES command is any valid server file type. Some examples are FOCUS, FOCEXEC, STY, PDF. or ACCESS. For a full list of valid file types, see Application and File Management Commands.

Example: Using the SYSFILES Table to Check File Existence

The following practical example of using the SYSFILES table to check file existence prints the filename myproc1 with extension fex (with the file type set to FOCEXEC). If no lines are returned, the file does not exist and the procedure exits. If the file exists, the procedure transfers to the point at which processing continues.

SQL FMI SET SYSFILES FOCEXEC
TABLE FILE SYSFILES
PRINT FILENAME ON TABLE HOLD 
WHERE FILENAME = 'myproc1' ;
WHERE EXTENSION = 'fex' ;
END
-IF &LINES GT 0 THEN GOTO RESUME
-TYPE Procedure Not Found ... exiting!
-EXIT
-RESUME