|
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.
|
In this section: |
The following commands return basic information about files and applications.
|
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.
STATE appname/filename.filetype -TYPE RETCODE &RETCODE
where:
Is the application under which the file is stored.
Is the name of the file.
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
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
|
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.
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:
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
|
How to: |
The APP QUERY command lists files within a given application. Applications and specific nested applications can be queried.
APP QUERY app1[/app1a...] [app2[/app2a]...] ... [appn[/appna]] [HOLD]
where:
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.
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
|
In this section: |
This section provides basic information about querying the server catalogs.
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.
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
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.
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
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.
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