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