TAA Tools
CVTIFS            CONVERT IFS                          TAAIFSA

The   Convert   IFS  command   converts   directory   entry   attribute
information  from the IFS  and outputs the  information to a  data base
file  named IFSDIRP  (for *TYPE1  output file  format) or  IFSDIRR (for
*TYPE2 output file format).   The file can  then be processed by  other
TAA  Tools (such  as  DSPIFS or  WRKIFS)  or user  written programs  to
extract desired information.

Two formats are available based on the OUTFILFMT parameter:

        OUTFILFMT      File        Format     Model file
        ---------      ----        ------     ----------

        *TYPE1         IFSDIRP     IFSDIRR    TAAIFSAP
        *TYPE2         IFSDIRT     IFSDIR2    TAAIFSAT

The  *TYPE2 format  contains  all of  the fields  from *TYPE1  plus the
IFOBJP field  (5000  bytes)  which has  the  actual path  name  of  the
object.  The *TYPE2 format is required for a tool such as WRKIFS.

To see a description of the format, enter:

        DSPFMT      TAAIFSAP
                OR
        DSPFMT      TAAIFSAT

You must  have use  authority to  the TAACVTIFS  authorization list  to
use CVTIFS.

The API used is Qp0lGetAttr.

A typical command would be:

        CVTIFS      OBJ('*') OUTLIB(xxx)

You  may  also   specify  a  list  of  IFS  objects/directories  to  be
included.  See the IFSLST tool and OBJ(*IFSLST).

Security discussion
-------------------

The CVTIFS  command  and  programs  must  be  run  by  a  user  who  is
authorized  to the  TAACVTIFS  authorization  list.   This  allows  the
command to  adopt authority during  execution so that  authority errors
can be avoided.

You are responsible for controlling who is authorized to TAACVTIFS.

The  program adopt function does not  operate on IFS objects.  However,
using program  adopt allows  the program  to swap  the current  profile
for QSECOFR  during the running of  the command and then  swaps back to
the  original  using  profile when  the  command  completes.   Swapping
occurs by the use of an API.

The swapping  of profiles  avoids conversion  problems,  but creates  a
problem in  that the  user could  use system  request to 'end  request'
during  the running of the  command and henceforth  operate as QSECOFR.
This is avoided  by making  the CL  program a  'request processor'  and
monitoring for  'end request'.   If 'end request'  occurs, the swap  of
profiles occurs back to the original profile.

Outfile discussion
------------------

One  record  is  written  for  each  directory  entry  along  with  its
attribute information.

Depending  on the OUTFILFMT  parameter either file  IFSDIRP (*TYPE1) or
file TAADIRT  (*TYPE2)  is  written.   File  IFSDIRT contains  all  the
fields  in IFSDIRP plus  the IFOBJP  field (5000  bytes) of  the actual
path name.

A special  field is used to link all  the directory entries back to its
starting path.  This field  is named IFDPTR (Parent Directory  Pointer)
and  contains  the  sequence  number of  the  directory  in  which  the
current directory entry is located.

A value  of zero in this field indicates  that the current directory is
the starting directory.   A  value of -1  in this  field indicates  the
current directory entry is the starting path.

There can  be multiple starting  path records.   This can occur  if the
path length is  very long.  Only 255 characters  are used in the IFDIRE
(Directory Entry) field.

Outfile Example
---------------

Assume  you  have  a  'home' directory  within  the  root  directory as
follows:

      - '/home/joe' has two subdirectories - Sub1 and Sub2
          and one stream file 'joe.txt'.

      - Subdirectory 'Sub1' has one subdirectory 'color' and
          and one stream file 'Sub1.txt'.

      - Subdirectory 'Sub2' has one subdirectory 'color' and
          and one stream file 'Sub2.txt'.

      - Subdirectory 'Sub1/color' has one stream file 'red.txt'

      - Subdirectory 'Sub2/color' has one stream file 'blu.txt'

    Name                Type        Size
    ----                ----        ----

    home                *DIR      16,391
      joe.txt           *DIR           7
         Sub1           *DIR       8,192
           Sub1.txt     *STMF          7
           color        *DIR       8,192
             red.txt    *STMF          7
         Sub2           *DIR       8,192
           Sub2.txt     *STMF          7
           color        *DIR       8,192
             blu.txt    *STMF          7
                                      --
                                  49,134

If  you  converted OBJ('/home/joe')  within  the  root  directory,  the
following 11 records  would be written to the  outfile (the field names
in the ISFDIRP file are described under the column headings):

                                                # of        Size of
           Parent   Object                      objs in     objs in
 Seq #     Seq #    Name     Type     Size      directory   directory
 -----     ------   ------   ----     ----      ---------   ---------
 IFSEQN    IFDPTR   IFDIRE   IFOTYP   IFOSIZ    IFTOBJ      IFTSIZ
 ------    ------   ------   ------   ------    ------      ------

    1         1-    /home                 0         0            0
    2         0     joe      *DIR     8,192         3       16,391
    3         2     Sub1     *DIR     8,192         2        8,199
    2         2     Sub2     *DIR     8,192         2        8,199
    5         2     joe.txt  *STMF        7         0            0
    6         2     color    *DIR     8,192         1            7
    7         3     Sub1.txt *STMF        7         0            0
    8         4     color    *DIR     8,192         1            7
    9         4     Sub2.txt *STMF        7         0            0
   10         6     red.txt  *STMF        7         0            0
   11         6     blu.txt  *STMF        7         0            0

Note the following:

  **   The first  record (Name = /home) does not  have a size.  This is
       the current path of the 'home/joe' object.

  **   Only object types  (such as directories)  that have sub  objects
       have entries in  the fields for '# of objects  in directory' and
       'size of  objects in directory'.   The information contains only
       the  objects  within   the  directory  and   does  not   include
       information on sub objects.

  **   The directory  itself  is not  included in  the count  of '#  of
       objects in directory' or the 'size of the directory'.

  **   If  the OMITDIR  parameter had  been  specified to  omit 'Sub1',
       Sub1 and all its contents would not appear.

  **   If  the  OMITDIR  parameter  had been  specified  to  omit 'S*',
       'Sub1' and 'Sub2' all their contents would not appear.

CVTIFS escape messages you can monitor for
------------------------------------------

      CPFA0A0    Object not found.
      TAA9891    Completion, but errors (see ESCAPE parameter)

Escape messages from based on functions will be re-sent.

Description of fields in outfile
--------------------------------

Most of the fields in  the outfile are self explanatory  when reviewing
the  format with  DSPFMT TAAIFSAP  or DSPFMT  TAAIFSAR.   The following
provides some additional description of some of the fields:

  **   IFTOBJ.    For Directory  type objects,  this  is the  number of
       objects within the directory.   It does not include the  objects
       in sub-directories.

  **   IFTSIZ.   For Directory type  objects, this  is the size  of the
       objects within  the directory.  It does  not include the objects
       in sub-directories.  This is the  actual size of the object  and
       could also be seen when viewed with a PC.

  **   IFASIZ.   For  Directory  type objects,  this  is the  allocated
       size  of the  objects  within the  directory.   This  size  is a
       better  representation of the size on  the system and the system
       does not describe the actual size of objects.

  **   IFDPRF.  For  Directory type objects,  this is a *YES/*NO  value
       for  whether any  of the  objects within  the the  directory are
       owned  by user type profiles.   It does not  include the objects
       in sub-directories.  The determination  of whether a profile  is
       a user profile is done using the RTVIBMPRF TAA Tool.

  **   IFDdates.   For  Directory  type objects,  these  dates are  the
       most current  date for all of the  objects within the directory.
       It does  not  include  the  objects  in  sub-directories.    The
       intent is to provide current information on a summary basis.

  **   IFUPRF a *YES/*NO value  for whether the object is  by user type
       profiles.   The  determination of  whether a  profile is  a user
       profile is done using the RTVIBMPRF TAA Tool.

  **   IFPGRP  The name of the  primary group of the  object.  *NONE is
       returned  if  the  object   does  not  have  a  primary   group.
       *NOUSRPRF is returned for the Network File System.

  **   IFCHDT The last change date to the attributes of the object.

  **   IFMODT The last  change date to the data  portion of the object.

  **   IFLORR  A L/R value for  whether the object  is local or remote.

  **   IFPGRP The primary group of the owning user profile.

  **   IFREAD A Y/N value  for whether the object  is a 'PC read  only'
       object.

  **   IFHIDD  A Y/N  value for  whether the  object is  a 'PC  hidden'
       object.

  **   IFSARC  A  Y/N   value  for  whether  the  object  needs  to  be
       archived.  This value is not reliable for Save/Restore.

  **   IFCKOU The user  who checked out  the data.  This  value is  set
       by the CHKOUT command and reset by CHKIN.

  **   IFPDIR The name of the parent directory.

  **   IFDPTR See the previous discussion.

  **   IFSEQN See the previous discussion.

  **   IFPROC An internal field used by CVTIFS.

Command parameters                                    *CMD
------------------

   OBJ           The path  name of  the object  to be  converted.   The
                 object  path name  can be  either a  simple name  or a
                 name   that  is   qualified  with  the   name  of  the
                 directory  in  which  the  object  is  located.    The
                 default is *.

                 Specifying  * will  start the  convert process  at the
                 current  directory level.    If the  current directory
                 level is at the root  ('/'), the convert process  will
                 start at the home directory ('/home').

                 The  special  value  of  *IFS  may  also  be  entered.
                 Specifying  *IFS  will start  the  convert  process at
                 the  root  directory  level  ('/')  excluding   /QDLS,
                 /QOPT and  /QSYS.LIB.   If additional directories  are
                 to be excluded, the OMITDIR parameter can be used.

                 The special  value *IFSLST may be entered  to refer to
                 a  list of  IFS objects/directories  entered using the
                 IFSLST tool (see the  WRKIFSLST command).  If  *IFSLST
                 is  entered, the  IFSLST  parameter must  name a  file
                 created by the CRTIFSLST command.

   OUTLIB        The  library  in  which the  file  IFSDIRP  or IFSDIRR
                 will be placed.   The default is  *LIBL.  If the  file
                 does not already exist, a library must be named.

   OUTMBR        The member  of the  IFSDIRP file  or the  IFSDIRR file
                 to  be used.   The default is  IFSDIR.  If  the member
                 does not exist, it is added.

   OUTFILFMT     The output file format to be used.

                 The default  is  *TYPE1 which  creates  file  IFSDIRP.
                 This contains  all descriptive  fields of the  object.
                 The model  file is TAAIFSAP with a  format of IFSDIRR.

                 Specifying   *TYPE2  will  create  the  file  IFSDIRT.
                 This  includes  all the  fields  of  *TYPE1  plus  the
                 IFOBJP  field (5000  bytes)  which  contains the  path
                 name  of the object.  The  model file is TAAIFSAT with
                 a format of IFSDIR2.

   REPLACE       A *YES/*NO  value for  whether  the member  should  be
                 cleared before writing  records into it.   The default
                 is *YES.

                 *NO  may be  specified to add  records to  an existing
                 member.

   PROCSUBDIR    If the  Object parameter  is  a directory,  specify  a
                 *YES/*NO    value    to    indicate     whether    all
                 subdirectories  relative to that  directory are  to be
                 included.  The default is *YES.

                 *NO  may be  specified to  process only  the directory
                 level.

   OMITDIR       If the  Object parameter  is a  directory, specify  up
                 to  10 subdirectory names  relative to  that directory
                 to be excluded.

                 Any  of the OMITDIR  entries may be  a subdirectory of
                 the directory  specified  for the  OBJ parameter.    A
                 subdirectory can  go multiple levels deep,  but cannot
                 skip any  directories along the way.   For example, if
                 'Sub1' is a  directory in the  home directory and  has
                 a  subdirectory   of  'Sub1A',   you  cannot   specify
                 OBJ('*') and OMITDIR('Sub1A').

                 Generic  directories are  supported by  using an  * as
                 the  last character of  an OMITDIR path.   This causes
                 any  directory starting  with  the  characters  before
                 the * to be omitted.

                 An omitted directory  cannot begin with a /  or \.  If
                 a  directory specified to  be omitted  does not exist,
                 no error occurs.

                 Examples:

                CVTIFS OBJ(*) OMITDIR('dir1')

                   Omits /home/xxx/dir1 and all its subdirectories

                CVTIFS OBJ(*) OMITDIR('dir*')

                   Omits /home/xxx/yyyy where yyyy is a subdirectory
                    beginning with 'dir' and all their subdirectories

   SELECT        A list of up  to ten values that  lets you include  or
                 omit  files and  objects.   The typical  use would  be
                 for  stream files  (*STMF).   This  provides selection
                 in addition to the  OBJ parameter.  Directory  entries
                 are always included.

                 The first  part of the  entry defaults to  *INCLUDE to
                 include all  of the values specified for  the 2nd part
                 of  the entry.   *OMIT may  be entered to  omit all of
                 the values specified  for the 2nd  part of the  entry.

                 The  second  part of  the  entry  identifies the  file
                 (can  be generic) and  its extension  (can be generic)
                 to be included/omitted.   The  default is  *ALL.   The
                 default can also  be considered to be '*'  or '*.*' Up
                 to 10 entries may be specified.

                 Embedded  asterisks  and ?   as  any  single character
                 are  not  supported.    The  matching  logic  is  case
                 insensitive (folded to upper case).

                 Examples:

                    *.txt   All files with a 'txt' extension
                    a*      All files where the name starts with 'a'
                    a*.b*   All files starting with 'a' and having
                               an extension that starts with 'b'
                    a.txt   All files named 'a.txt'
                    a       All files named 'a' (without an extension)

                 Multiple * values  are allowed to represent 0  or more
                 characters.    For   example,  any  of  the  following
                 arguments   would   match   a  file   with   the  name
                 'empty.html'.  Case is ignored.

                    empty.hmtl
                    emp*.ht*
                    *e*M*p*h*t*

   IFSLST        If OBJ(*IFSLST)  is  specified, the  IFSLST  parameter
                 must  name   a  file   created  by  CRTIFSLST.     The
                 WRKIFSLST  command is used to  enter directory records
                 into the file.

   ESCAPE        A *YES/*NO parameter  for whether  to send TAA9891  as
                 an escape  message if  errors occur  such as a  locked
                 object.    The  message  will  be  sent  as  either  a
                 diagnostic  or  escape  message  if  prior  diagnostic
                 messages indicate that errors have occurred.

                 *NO  is the  default  which  will  send TAA9891  as  a
                 diagnostic type message.

                 *YES  may be specified  to send  TAA9891 as  an escape
                 message.

   USRPRF        The  user profile that will  be switched to during run
                 time.   QSECOFR  is the  default.   For  file  systems
                 (such as  QNTC), CVTIFS will fail if  QSECOFR does not
                 exist.

                 *CURRENT  may be used or a  specific user profile, but
                 the profile must have *ALLOBJ special authority.

   CVTDDIR       A *YES/*NO parameter  for whether  to convert  entries
                 that are in a distributed directory such as QNTC.

                 *NO is the default to prevent conversion.

                 *YES   may  be   specified   to  convert   distributed
                 directory   entries.     You   must   understand  your
                 environment if *YES  is to  be used.   It is  possible
                 to  loop  when  *YES is  specified  if  a  distributed
                 directory   contains  another   distributed  directory
                 that  maps back  to a  previously processed directory.

Restrictions
------------

You must  have use  authority to  the TAACVTIFS  authorization list  to
use CVTIFS.

Up to 10 subdirectory names are allowed for the OMITDIR parameter.

Object names are limited to 255 characters in the outfile.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CRTDUPPF        Create duplicate PF
     RTVSYSVAL3      Retrieve system value 3
     SNDSTSMSG       Send status message
     SNDDIAGMSG      Send diagnostic message
     SNDESCMSG2      Send escape message
     SNDCOMPMSG      Send completion message
     RTVIBMPRF       Retrieve IBM Profile

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   CVTIFS        *CMD                   TAAIFSA       QATTCMD
   TAAIFSAC      *PGM    CLP            TAAIFSAC      QATTCL
   TAAIFSAC2     *PGM    CLP            TAAIFSAC2     QATTCL
   TAAIFSAR      *PGM    RPGLE          TAAIFSAR      QATTRPG
   TAAIFSAP      *FILE   PF             TAAIFSAP      QATTDDS
   TAAIFSAQ      *FILE   PF
   TAAIFSAT      *FILE   PF             TAAIFSAT      QATTDDS
   TAAIFSAU      *FILE   PF

TAAIFSAQ  and TAAIFSAU  are  additional versions  that mirror  TAAIFSAP
and TAAIFSAT.
					

Added to TAA Productivity tools August 15, 2001


Home Page Up to Top