FTOUCH Utility

#### Search Results

Search

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

- Using the Utility FTOUCH

- Syntax of ftouch

- Examples of ftouch

#### Related Topics:

- The File FILEDIR.SAG - Operations documentation

- Using NFS to Store Natural Libraries - Operations documentation

- Transferring Natural Generated Programs - Programming Guide

## 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.

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: If the Natural default buffer pool is not active or if the specified buffer pool does not exist, an appropriate error message is displayed. 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.

### On this page

- Using the Utility FTOUCH
- Syntax of ftouch
- Examples of ftouch