FTOUCH Utility

The FTOUCH utility is used to make a downloaded object executable by Natural. This is done by importing the object into the Natural system file FNAT or FUSER and updating the FILEDIR.SAG file.

Note:
Using the FTOUCH utility is limited to 60000 objects because this is the maximum number of entries in the file FILEDIR.SAG.

The FTOUCH Utility documentation covers the following topics:

Related Topics:

Using the Utility FTOUCH

This section provides instructions for executing the FTOUCH utility.

Note:
Terms enclosed in brackets ([ ]) are optional; bold letters are actual values that must be entered as shown.

Start of instruction set To execute the FTOUCH utility

  1. Go to an operating system command prompt.

  2. Ensure that the transferred file is in the desired FNAT or FUSER directory (as specified in your global configuration file) and has the correct extension.

  3. Enter the command ftouch using the following syntax: 

    ftouch [fnat=dbid,fnr] [fuser=dbid,fnr][bp=bp-name]
[parm=parm-file] [lib=library-name] [encoding=encoding-name]
[userep=rep-use] [-ignoreext][-v] [-q] [mode] [kind] files

    Or:
    For migration, use the following syntax: 

    ftouch [fnat=dbid,fnr] [fuser=dbid,fnr]
[parm=parm-file] [lib=library-name][encoding=encoding-name][-q] convert

    Or:
    For endian conversion of the FILEDIR.SAG file, use the following syntax: 

    ftouch [fnat=dbid,fnr] [fuser=dbid,fnr] 
[parm=parm-file] [lib=library-name][endian=endian-mode]

    Or:
    For encoding of single or multiple objects contained in the FILEDIR.SAG file, use the following syntax: 

    ftouch [fnat=dbid,fnr] [fuser=dbid,fnr]
[parm=parm-file] [lib=library-name][objname=object-name][encoding=encoding-name]

    Or:
    For setting the line number suppression state of a library in FILEDIR.SAG, use the following syntax: 

    ftouch [fnat=dbid,fnr] [fuser=dbid,fnr] 
[parm=parm-file] [lib=library-name][suprln=library-state]

Syntax of ftouch

The following options are provided with the ftouch command:

Option Explanation
fnat=dbid,fnr  

Specifies the database ID and file number of the FNAT system file to be used; default is the value specified in the NATPARM parameter file.

See also Example 2.

fuser=dbid,fnr  

Specifies the database ID and file number of the FUSER system file to be used; default is the value specified in the NATPARM parameter file.

See also Example 2.

bp=bp-name  

Specifies the buffer pool to be used. You can omit the bp-name if you want to use the Natural default buffer pool NATBP; otherwise, you have to specify the appropriate bp-name.

Notes:

  1. If the Natural default buffer pool is not active or if the specified buffer pool does not exist, an appropriate error message is displayed.
  2. Do not delete the default buffer pool NATBP, as it is possible that Natural may no longer function properly.
parm=parm-name   Specifies the name of the parameter file to be used if you want to use a parameter file other than the default NATPARM parameter file.
lib=library-name   Specifies the library to be used. You can omit the library-name if you are already in the appropriate subdirectory; otherwise you have to specify the appropriate library-name.
userep=rep-use
Specifies whether to use the repository or not. rep-use must be one of the following:
 
ON The repository is used.
 
OFF The repository is not used.
-v Displays statistics on disk I/O operations during processing.
-q Indicates that quiet mode is to be used: only error messages but no status messages are displayed.
-ignoreext Specifies that files with unkown extensions contained in a library are ignored. The -ignoreext option can be combined with one of the following options:
-a
-d
mode 

Specifies the programming mode; sm specifies that a program is in structured mode; the default is reporting mode.

See also Example 1.

kind  

Specifies the subdirectories SRC and/or GP for input; it can be one of the following:

-s     for source objects (default),
-g for cataloged objects/generated programs,
-b for both source objects and cataloged objects/generated programs.

See also Example 2.

files

Specifies the files to be processed; you can specify filename.ext for individual files or:

-a    to add new files; all files in the directory which are not currently found in FILEDIR.SAG are added (already existing files are not touched).
-d to build a new FILEDIR.SAG directory.

Caution:
Be careful when using this option, since the old FILEDIR.SAG is deleted and rebuilt from scratch.

See also Example 4.

-f Forces an update of the specified object's timestamp in FILEDIR.SAG. This option can only be specified if an individual file has been specified with the files option (see above).
convert

Indicates that an old FILEDIR.SAG file is to be migrated. The FILEDIR.SAG file from a Natural version earlier than Version 6.2 is converted into a new portable FILEDIR.SAG file. A copy of the original (old) FILEDIR.SAG file is saved as FILEDIR.BCK file in the directory of the specified library. If a FILEDIR.BCK file already exists in the specified library, the old FILEDIR.SAG will not be converted.

For further information, see Portable Natural System Files in the Operations documentation.

See also Example 3 and Example 5.

sync

Indicates that the specified library and system files are to be synchronized between Natural and the repository (Windows only); this function must be executed each time FILEDIR.SAG is modified by FTOUCH.

Caution:
When specifying sync, ensure that either userep=ON is set or the Natural profile parameter USEREP is set to ON.

encoding=encoding-name

Specifies the code page to be used for the files contained in FILEDIR.SAG.

The encoding option generates or changes the internal code page information maintained in FILEDIR.SAG for each object affected by the ftouch command. This option does not convert the contents of a source object or a cataloged object/generated program.

The encoding option can be combined with the following options:

-a    
-d
convert
objname

encoding-name can be any code page name valid with the CP session parameter specified in the NATPARM parameter file. See also CP - Default Code Page Name in the Parameter Reference.

See also Example 4, Example 5, Example 7 and Example 8.

endian=endian-mode

Specifies the endian format to be used for the FILEDIR.SAG directory.

The endian option applies to the entire FILEDIR.SAG directory.

The option does not apply when adding files to FILEDIR.SAG or when generating a new FILEDIR.SAG.

endian-mode can be one of the following formats:

BIG Converts to big endian.
LITTLE Converts to little endian.
DEFAULT Converts to the endian format used on your current platform.

See also Example 6.

objname=object-name

Selects the object(s) for which to maintain internal format information in FILEDIR.SAG.

The objname option only applies if the encoding option is specified.

object-name selects all objects with names equal to the specified value. You can use asterisk (*) notation for a name range.

See also Example 7 and Example 8.

suprln=library-state
Specifies whether the line number suppression state is set for the specified library. library-state must be one of the following:
 
ON Source line numbers are not written to the files contained in FILEDIR.SAG, when saving the sources of the objects contained in this library.
OFF Source line numbers are written to the files contained in FILEDIR.SAG.

Examples of ftouch

The following section provides examples of the ftouch command.

Example 1:

Change to the following directory:   fuser-directory/TESTLIB/SRC
Enter the following command: ftouch sm TESTFILE.NSP

As a result, the program TESTFILE in library TESTLIB is available in structured mode to Natural.

Example 2:

Change to the following directory:     fuser-directory/MYLIB
Enter the following command: ftouch fnat=21,21 fuser=22,22 -b

As a result, all files in the directories MYLIB/SRC and MYLIB/GP are available in reporting mode (default) to Natural.

Example 3:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB convert

As a result, a new portable FILEDIR.SAG file is saved for the MYLIB library and the old FILEDIR.SAG is saved as FILEDIR.BCK file in this library.

Example 4:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB encoding=UTF-8 -a -s

As a result, the internal format information is generated as UTF-8 for all objects which are added to the FILEDIR.SAG directory from the MYLIB/SRC subdirectory.

Example 5:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=OLDLIB encoding=windows-1251 convert

As a result, a new portable FILEDIR.SAG file is saved for the OLDLIB library and the internal format information changes to windows-1251 for all objects contained in the FILEDIR.SAG file.

Example 6:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB endian=BIG

As a result, the FILEDIR.SAG file of the MYLIB library is converted to big endian. The internal format information changes to BIG for all objects contained in the MYLIB library.

Example 7:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB objname=MYPROG1 encoding=UTF-8

As a result, the internal format information of object MYPROG1 changes to UTF-8 if MYPROG1 is contained in library MYLIB in the FILEDIR.SAG file.

Example 8:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB objname=MY* encoding=UTF-8

As a result, the internal information of all objects with names that start with MY changes to UTF-8 if they are contained in library MYLIB in the FILEDIR.SAG file.

Example 9:

Change to the following directory:     fuser-directory
Enter the following command: ftouch lib=MYLIB suprln=ON

As a result, the line number suppression state is set to ON for library MYLIB in the FILEDIR.SAG file.