The Integrated File System

Business programming on the iSeries usually involves the processing of data stored in relational database tables, either through record-oriented input-output operations or through SQL. But some data doesn't fit well in relational databases, such as files containing pictures or sound. Other data and applications come from systems in which the relational database isn't an integral part of the operating system. For this reason, IBM expanded the OS/400 file system in V3R1 to include a nondatabase method of storing data. The name of this expanded file system is the Integrated File System , or IFS .

It is important for iSeries professionals to understand the IFS because of the growing importance of nondatabase data and applications in iSeries installations. Since Qshell is an effective interface to the IFS, iSeries professionals would do well to gain an understanding of Qshell.

Organization

The IFS includes various file systems. Different releases of OS/400 define different file systems, but some of the most common ones are listed in Table 9.1. All of these file systems can be accessed through common user interfaces, one of which is Qshell. Other user interfaces are CL commands and iSeries Navigator.

You can use any or all of the file systems depending on the data you are accessing. The Root and the QOpenSys file systems will probably be the file systems you work with the most.

Each file system has distinct functional and performance characteristics. For example, file names in the root system are not case sensitive, but those in QOpenSys are case sensitive. Similarly, file names in the root system may be up to 255 characters long, but a QDLS file name may have only eight characters , plus a zero- to three-character extension.

Directories

A directory is a container for files and other directories. All IFS file systems are organized into directories. The main directory is the root, which contains all the file systems and may also contain other directories and files.

To create a directory, use Qshell's mkdir command. For example, the following command creates a directory named bin :

mkdir bin

To delete a directory, it must first be empty. If it is, you can use Qshell's rmdir command:

rmdir bin

To delete a directory that is not empty, use the rm command with the -r or -R option. For example, the following command deletes the bin directory, all its subdirectories, and the files they contain:

rm -r bin

Be sure you know what you're doing, however, because once a file has been deleted, you can't recover it.

Home and Current Directories

The current directory is the directory where Qshell looks for and stores files when no directory path is specified. That is, if the object reference does not begin with a slash character, Qshell assumes the object is in, or is to be placed in, the current directory.

The following two lines illustrate the use of the home directory in a Qshell cat command:

cat ftpmodel.txt cat /home/ftpmodel.txt

In the first line, Qshell looks for the ftpmodel.txt file in the current directory. In the second line, Qshell looks for the ftpmodel.txt file in directory/home.

In the following command, member EDITX of source physical file JSMITH/ QRPGLESRC is copied to IFS file editx.txt in the current directory:

cp /qsys.lib/jsmith.lib/qrpglesrc.file/editx.mbr editx.txt

This command uses the IFS naming conventions for library objects in the QSYS.LIB file system. Naming library objects in the QSYS.LIB file system is discussed later in this chapter.

A user's home directory becomes the current directory at sign-on. The name of the home directory is stored in the user profile. Use the HOMEDIR parameter of the Create User Profile command (CRTUSRPRF) or the Change User Profile command (CHGUSRPRF) to specify a user's home directory. You may also use certain abbreviations to specify the home or current directory, as shown in Table 9.2.

To change the current directory from within Qshell, use the cd command. Issuing this command without arguments, or with the tilde argument by itself, changes to the home directory:

cd cd ~

Following the tilde with a user name produces a different result:

cd ~jsmith

In this case, user jsmith's home directory becomes the current directory.

Issuing the cd command with the slash argument causes the root directory to become the current working directory:

cd /

In the following example, the PS1 variable, Qshell's primary prompt string, has been set to show the current directory followed by a dollar sign:

/ $ cd /usr/bin /usr/bin $

The root directory is the current directory before the cd command runs. The cd command changes to the /usr/bin directory, which is under the root directory.

The cd command changes two predefined Qshell variables, PWD and OLDPWD. PWD is set to the name of the new current directory. OLDPWD is set to the name of the current directory before the change. Usage of these two variables is shown in Figure 9.1.

print "Current dir=$PWD" Current dir=/home/JSMITH $ cd bin $ print "Current dir=$PWD; previous dir=$OLDPWD" Current dir=/home/JSMITH/bin; previous dir=/home/JSMITH

Figure 9.1: Before the cd command, the current directory is /home/JSMITH. After, the current directory is /home/JSMITH/bin.

By default, the Qshell prompt is a dollar sign. It is a good practice to make Qshell display the name of the current directory in the prompt. As Figure 9.2 shows, you can do this by placing the PWD variable in the primary prompt string, which in this example is variable PS1. Notice that the prompt changes as the current directory is changed.

$ PS1='$PWD $' /home/JSMITH $ cd bin /home/JSMITH/bin $ cd /qdls /qdls $ cd /home/JSMITH $

Figure 9.2: Before the assignment operation, the primary prompt is the dollar sign. After the assignment, the prompt is the name of the current working directory followed by a dollar sign.

To display the name of the current working directory in the prompt every time you use Qshell, set the primary prompt string in the .profile file in your home directory and include an export command so that the interactive shell will see the assignment:

PS1='$PWD $' export PS1

The .profile script is executed every time Qshell is started.

Paths

The IFS provides for all files to be accessed in a similar manner, regardless of the file systems of which they are a part. Each file system is a directory under the root. The system finds a file by traversing a series of hierarchically organized directories.

The syntax for a path name is similar to path names in DOS/Windows-based and Unix-like systems. Directories are separated from one another and from a file name by the forward slash character. An initial slash indicates the root directory, under which all directories are organized. For example, the following command copies file spc.h in the QOpenSys file system to directory /home/jsmith in the root system:

cp /qopensys/usr/include/spc.h /home/jsmith

IFS Names for Library Objects

The library system that has been part of OS/400 since the System/38 is known to the IFS as QSYS.LIB. To reference an object in the library system, follow the object name with a period and the object type. Examples of object types and abbreviations are listed in Table 9.3. Note that Qshell sometimes allows these abbreviations to be written in either uppercase or lowercase, but other times accepts only uppercase.

Although the library system is not directory-based, objects are referenced with a directory-like syntax. Libraries are treated as if they were subdirectories of the QSYS library. Objects appear to be files or directories within a library. Objects that can be further subdivided, such as database files, appear as directories. The subdivisions, such as physical or logical file members , appear to be files within directories.

Figures 9.3 and 9.4 demonstrate the use of library objects within Qshell ls commands.

ls /qsys.lib/jsmith.lib DIVBY0.QRYDFN MON001.PGM PROTOS.FILE SRC.FILE DIVBYZERO.FILE MONEVAL4.PGM PROTOTYPES.FILE JSMITH.JOBD EDITX.PGM MONEVAL5.PGM QRPGLESRC.FILE

Figure 9.3: The ls (list directory contents) command lists the names of objects in library JSMITH.

ls /qsys.lib/jsmith.lib/qrpglesrc.file EDITX.MBR EDITX2.MBR EDITX3.MBR MON001.MBR

Figure 9.4: The ls command displays the names of the members in source physical file JSMITH/QRPGLESRC.

In the following command, member EDITX of source physical file JSMITH/ QRPGLESRC is copied to IFS file editx.txt in directory/home/jsmith:

cp /qsys.lib/jsmith.lib/qrpglesrc.file/editx.mbr /home/jsmith/editx.txt

The cat command in Figure 9.5 shows the source code for RPG program EKOR1, which is stored in file QRPGLESRC in library JSMITH. To call a program within the Qshell environment, type in the name of the program object using the IFS naming convention. This example shows how to call program EKOR1 in library JSMITH.

cat /qsys.lib/jsmith.lib/qrpglesrc.file/ekor1.mbr H*dftactgrp(*no) actgrp('QILE') bndsrvpgm(qtcp/qtmhcgi) D OutputData s 4096 varying D EOL c const(x'0D25') D ErrorDS ds 16 D BytesProv 10i 0 inz(%size(ErrorDS)) D BytesAvail 10i 0 D ExceptionID 7 D WriteStdout pr extproc('QtmhWrStout') D Buffer 4096 varying D BufferLen 10i 0 const D Error like(ErrorDS) /free OutputData = 'This is a test.' + EOL + EOL; WriteStdOut (OutputData: %len(OutputData): ErrorDS); WriteStdOut (ExceptionID: 7 : ErrorDS); *inlr = *on; /end-free /home/JSMITH $ /qsys.lib/jsmith.lib/ekor1.pgm This is a test.

Figure 9.5: To call a program within Qshell, type its name in IFS format and press Enter.

In most cases, Qshell permits you to use either uppercase or lowercase when specifying object names in the library system. However, in certain cases, such as during parameter expansion, Qshell only matches uppercase characters . For example, Figure 9.6 lists the names of all files in JSMITH/SRC that begin with the letters md .

ls /qsys.lib/jsmith.lib/src.file/md*.mbr ls: 001-2113 Error found getting information for object /qsys.lib/jsmith.lib/src.file/md*.mbr. No such path or directory. /home/JSMITH $ ls /qsys.lib/jsmith.lib/src.file/md*.MBR ls: 001-2113 Error found getting information for object /qsys.lib/jsmith.lib/src.file/md*.MBR. No such path or directory. /home/JSMITH $ ls /qsys.lib/jsmith.lib/src.file/MD*.mbr ls: 001-2113 Error found getting information for object /qsys.lib/jsmith.lib/src.file/MD*.mbr. No such path or directory. /home/JSMITH $ ls /qsys.lib/jsmith.lib/src.file/MD*.MBR /qsys.lib/jsmith.lib/src.file/MDATE.MBR /qsys.lib/jsmith.lib/src.file/MDATET1.MBR /qsys.lib/jsmith.lib/src.file/MDATEV1.MBR

Figure 9.6: Wildcard portions of QSYS.LIB path names must be in uppercase.

The distinction between the situations in which Qshell accepts lowercase and when it requires uppercase can be a little confusing. In general, the processing that Qshell does is case sensitive, while the processing done by QSYS.LIB is case-insensitive.

To understand this, consider the details behind Figure 9.6. To execute the ls command, Qshell must first perform parameter expansion on the path name. To expand the parameter, Qshell first uses the file system to retrieve a list of all files in the src.file directory. Among other files, the list of files returned from the QSYS.LIB file system contains MDATE.MBR, MDATET1.MBR and MDATEV1.MBR After retrieving the list, Qshell matches the md*.mbr expression to the file names returned. Since Qshell is case sensitive, no files matching the expression are found. When Qshell performs the same parameter expansion again, using MD*.MBR, the file names match the pattern.

Compare this with the example in Figure 9.5. For the commands shown there, Qshell does not need to process the file name or directory strings. Instead, the file names are used to open or run the QSYS.LIB file objects directly. Since the QSYS.LIB file system is case-insensitive, the lowercase names are accepted and Qshell uses the objects.

The case-sensitivity of Qshell combined with the case-insensitivity of the file system is similar for any file systems that are case-insensitive. For example, similar behavior occurs in the case-insensitive root file system.

Relative Paths

If a path name does not begin with a slash, it is a relative path. That is, the path is assumed to begin from the current directory. Figure 9.7 shows the use of relative paths in cd bin commands.

/home/JSMITH $ cd bin /home/JSMITH/bin $ cd /usr /usr $ cd bin /usr/bin $

Figure 9.7: The first command changes to directory /home/JSMITH/bin, while the second one changes to /usr/bin. The prompt string shows the name of the current directory.

In Figure 9.8, the ls and rm commands refer to the current directory, since no directory name is given. Note that file names are case sensitive in the QOpenSys file system.

cd /QOpenSys /QOpenSys $ ls MyData.CSV QIBM QSR usr /QOpenSys $ rm mydata.csv rm: 001-2103 Error found getting information for file or directory mydata.csv. No such path or directory. /QOpenSys $ rm MyData.CSV /QOpenSys $ ls QIBM QSR usr

Figure 9.8: The cd command changes the current directory to QopenSys, a POSIX-type file system.

You may use the abbreviations from Table 9.2 in relative path names. For example, the following command moves the ftptemp file from the current directory to the home directory:

mv ftptemp ~

More examples showing the use of abbreviations in relative path names are given in Figures 9.9 and 9.10.

/usr/bin $ cd .. /usr $ cd .. / $

Figure 9.9: The prompt string shows the name of the current directory. The two periods are an abbreviation indicating the parent directory.

cp ftprun.qsh ../bin /home/JSMITH/ftp $

Figure 9.10: The copy command copies the ftprun.qsh file from the current directory to the bin directory that shares the same parent directory. The current directory is /home/JSMITH/ftp, so the file is copied to /home/JSMITH/bin.

Links

Until the IFS was added to OS/400, every object had one name ”no more, no less. A library had a name, a job description had a name, a program had a name, and so on. To run a program, you just placed that program's name in the first parameter of a CALL command.

In the real world, however, one person, place, or thing can have many names. Consider the fictitious user featured throughout this book. Suppose that, according to his birth certificate, he is "Joseph Robert Smith," but nobody calls him that. When signing legal documents, he is "Joseph R. Smith." To his mother, he is "Joey." To his wife, he is "Sweetheart." To his children, he is "Dad." To his old college buddies , he is "Joe Bob." All of these are names for the same person, and in a complex world, we might uniquely identify that person with a specific number, much like a United States Social Security number.

Similarly, the IFS allows one object to have more than one name. Under the IFS, each object has a unique inode number instead of a name. All internal references to an object contain the inode number. The system stores information about how objects are referenced by directories. Each of these references, or directory entries, is called a link to the object. It is the link, not the target object, which has a name. There are two types of links: hard links and symbolic , or soft , links.

Creating Hard Links

A hard link provides direct access to an object. When you create an object, the name you provide becomes the name of the first hard link to the object. You may add other hard links, in effect giving more than one name to a file.

To add a hard link, use the ln command. You may use any of the following forms:

ln path/existing_file ln existing_file new_link ln existing_file target_dir ln existing_file existing_file target_dir

The term target_dir represents a directory into which the new link will be placed.

The ln command takes, one, two, or more arguments. If only one argument is given, as in the following example, the argument points to an existing file:

ln bin/ftprun.qsh

A hard link named ftprun.qsh is created in the current directory. It points to the file ftprun.qsh in the bin directory. The same file appears to be in both directories, but the file is stored in only one location, with links to the file in two directories.

If two arguments are given, the first one is the name of an existing file. The second argument may be the name of a new file or a directory in which to create a link of the same name.

The following command creates a link called arglist.qsh in the bin directory that is under the current directory. The link will point to the same file as the showargs.qsh link in /home/jsmith/shellwork:

ln /home/jsmith/shellwork/showargs.qsh bin/arglist.qsh

Here is another example:

ln /home/jsmith/shellwork/showargs.qsh bin

This command creates a link called showargs.qsh in the bin directory that is under the current directory. The link will point to the same file as the showargs.qsh link in /home/jsmith/shellwork.

If three or more arguments are given, as in Figure 9.11, the last argument is a directory into which the new links are to be placed. The other arguments are the names of existing files for which new links are to be created. The ln command in Figure 9.11 creates hard links in the new temp directory. The links are to certain files in the current directory (err.txt, all files whose names begin with out, and upper.txt). The hard links have the same names as the files whose links were copied .

mkdir temp /home/JSMITH $ ln err.txt out* upper.txt temp /home/JSMITH $ ls temp err.txt out.txt out3 output01.qsh out.log out1 output.txt upper.txt /home/JSMITH $

Figure 9.11: A new directory called temp is created under the current directory, /home/JSMITH.

As mentioned earlier, objects have inode numbers instead of names. All hard links to an object reference the same inode number. To see an object's inode number, use the -i option of the ls command, as shown in Figure 9.12. The number of hard links follows the permissions and precedes the owner's name.

ls -il phonedir.csv 115068 -rw-rw---- 1 SMITH 0 52 Oct 3 11:26 phonedir.csv /home/JSMITH $ cat phonedir.csv Larry,22,543-9876 Moe,24,333-7777 Curly,18,234-7890 /home/JSMITH $ ln phonedir.csv phonenumbers.txt /home/JSMITH $ cat phonenumbers.txt Larry,22,543-9876 Moe,24,333-7777 Curly,18,234-7890 /home/JSMITH $ ls -il phonedir.csv 115068 -rw-rw---- 2 SMITH 0 52 Oct 3 11:26 phonedir.csv /home/JSMITH $ ls -il phonenumbers.txt 115068 -rw-rw---- 2 SMITH 0 52 Oct 3 11:26 phonenumbers.txt /home/JSMITH $

Figure 9.12: All hard links to an object reference the same inode number.

The first ls command in Figure 9.12 shows that file phonedir.csv's inode number is 115068, and that there is one hard link. The first cat command shows the contents of the phonedir.csv file. There are three records. The ln command creates a hard link to the same inode. The new link is called phonenumbers.txt. The second cat command shows that the phonenumbers.txt file has the same content as the phonedir.csv file. The last two ls commands show that the two files have the inode numbers, and that there are two hard links to the same object

As you work with hard links, keep in mind some limitations:

• Hard links cannot cross file systems. For example, you cannot create a hard link in the QOpenSys file system to an object in the QSYS.LIB system. If you attempt to create such a link, Qshell responds with error 001-2137 ("Error found creating link xxxxx to object zzzzz. Improper link").
• A hard link cannot be created to an object that does not exist.
• Some file systems, like QSYS.LIB, do not support hard links.

Removing Links

Qshell does not have a delete command. Instead of deleting files and directories, you remove links to the object. When the last hard link is removed, Qshell deletes the object, unless that object is in use at the time. In that case, the object is deleted when it is no longer in use.

The following two examples illustrate the removal of links:

• Remove the link named err.txt from the current directory:

  rm err.txt

• Remove the links whose names begin with out in directory /home/jsmith/temp:

  rm /home/jsmith/temp/out*

It is important to understand the distinction between removing a link to an in-use file compared to actually deleting an in-use file. When a file is in use, it's reasonable to assume that the file system retains some kind of lock on the file. By deleting an in-use file, you would either have to wait for a lock on the file, or cause some sort of error to the program accessing the file. By removing a link, the file system deletes only the name to the file. The currently running application does not notice this and continues using the file safely. Only the next attempt to open the file will find that the file name no longer exists.

Symbolic Links

Symbolic links address the limitations of hard links. It's easiest to think of a symbolic link as a file that contains a text string representing the path to a target object. You might also think of a symbolic link as a shortcut to an object. Symbolic links have two important advantages over hard links.

• Symbolic links may cross file systems.
• Symbolic links may point to objects that do not exist.

The second point may also be viewed as a disadvantage , since it is possible to clutter the system with symbolic links that are obsolete.

To create a symbolic link, use the -s option with the ln command, as shown in Figure 9.13. Two symbolic links have been created in the root file system. Both point to program object RAPR in library JS. Notice that the number of hard links (in the second column) is one.

ln -s /qsys.lib/js.lib/rapr.pgm /home/JSMITH $ ln -s /qsys.lib/js.lib/rapr.pgm rapr /home/JSMITH $ ls -l rapr* lrwxrwxrwx 1 SMITH 0 30 Oct 2 4:34 rapr -> /qsys.lib/js.lib/rapr.pgm lrwxrwxrwx 1 SMITH 0 03 Oct 2 4:34 rapr.pgm -> /qsys.lib/js.lib/rapr.pgm

Figure 9.13: Use the s option to create symbolic links.

In general, symbolic links behave like, and are managed identically to, hard links. Table 9.5 provides a brief comparison of hard and symbolic links.

Displaying the Contents of IFS Files

Because Qshell is tightly coupled to the Integrated File System, it is hardly surprising that Qshell includes commands that retrieve IFS data and display it in various formats. This section presents the utilities that are most commonly used to display the contents of IFS files.

The Cat Utility

The cat utility shown in Figure 9.14 concatenates one or more files and sends the output to standard output, which by default is the terminal session in an interactive job. By default, cat treats files as text. That is, the file is converted to the job's CCSID before being displayed. This allows you to view any text file in a readable format, regardless of its character set. If you need cat to work in binary mode, use the -c option.

cat ftpmodel.txt one zxcvb put INPUTFILE OUTPUTFILE quit /home/jsmith $

Figure 9.14: The cat utility provides an easy way to display the contents of a file.

The Pr Utility

The pr utility copies the contents of one or more files to standard output. It is similar to cp , except that pr formats and paginates the data. The pr utility can do the following:

• Start printing at a certain page of output
• Number lines
• Format a stream of records into multiple columns
• Double-space the output
• Expand tab characters to appropriate numbers of spaces
• Print a heading of your choosing at the top of each page of output
• Print multiple files side by side

However, pr cannot write to a printer file from an interactive session. To copy the paginated output to a printer file, you must use the Rfile utility, discussed in Chapter 20.

Figure 9.15 shows the pr utility paginating the goodoleboys.txt file into 66-line pages with blank lines at the top and bottom of each page. The default page heading shows the date and time, the file name , and the page number.

pr goodoleboys.txt Oct 22 22:18 2002 goodoleboys.txt Page 1 Name Born Phone Dog Wife Shotgun Paid ========= ======== ======== ======== ========= ======== ===== Chuck Dec 25 444-2345 Blue Mary Sue 12 .50 Bubba Oct 13 444-1111 Buck Mary Jean 12 Billy Bob June 11 444-4340 Leotis Lisa Sue 12 Amos Jan 4 333-1119 Amos Abigail 20 Otis Sept 17 444-8000 Ol' Sal Sally 12 Claude May 31 333-4340 Blue Etheline 12 Roscoe Feb 2 444-2234 Rover Alice Jean 410 Arlis June 19 444-1314 Redeye Suzy Beth 12 .75 Junior April 30 BR-549 Percival Lilly Faye 12 Bill Feb 29 333-4444 Daisy Daisy 20 Ernest T. ?? none none none none ( ... more blank lines omitted ...)

Figure 9.15: This command paginates the goodoleboys.txt file into 66-line pages.

The pr command in Figure 9.16 also paginates the goodoleboys.txt file. This time, however, a colon separates the line number from the data, and instead of the file name, "Membership List" is printed in the title.

pr -n:3 -h "Membership List" goodoleboys.txt Oct 22 22:18 2002 Membership List Page 1 1:Name Born Phone Dog Wife Shotgun Paid 2:========= ======== ======== ======== ========= ======= ===== 3:Chuck Dec 25 444-2345 Blue Mary Sue 12 .50 4:Bubba Oct 13 444-1111 Buck Mary Jean 12 5:Billy Bob June 11 444-4340 Leotis Lisa Sue 12 6:Amos Jan 4 333-1119 Amos Abigail 20 7:Otis Sept 17 444-8000 Ol' Sal Sally 12 8:Claude May 31 333-4340 Blue Etheline 12 9:Roscoe Feb 2 444-2234 Rover Alice Jean 410 10:Arlis June 19 444-1314 Redeye Suzy Beth 12 .75 11:Junior April 30 BR-549 Percival Lilly Faye 12 12:Bill Feb 29 333-4444 Daisy Daisy 20 13:Ernest T. ?? none none none none ( ... more blank lines omitted ...)

Figure 9.16: This version of pr prints the goodoleboys.txt file with different options.

The Od Utility

The od utility dumps files in a variety of formats, including character, hexadecimal, octal, signed decimal, unsigned decimal, and floating point, as shown in Figure 9.17. Be aware, however, that the a and c formats, which dump data in character format, only work for EBCDIC character sets. Also, unprintable data in character format is represented by three-digit octal numbers. In the results from the first command in Figure 9.17, octal 045 represents the linefeed character, with which each record ends.

cat personal.data My name is Joe Smith. I like cheese. /home/jsmith $ od -t c personal.data 0000000 M y n a m e i s J o e S 0000020 m i t h . 045 I l i k e c h e 0000040 e s e . 045 0000051 /home/jsmith $ od -t x personal.data 0000000 d4a84095 81948540 89a240d1 968540e2 0000020 9489a388 4b25c940 93899285 40838885 0000040 85a2854b 25000000 0000051 /home/jsmith $ od -tx1c personal.data 0000000 0d4 0a8 040 095 081 094 085 040 089 0a2 040 0d1 096 085 040 0e2 M y n a m e i s J o e S 0000020 094 089 0a3 088 04b 025 0c9 040 093 089 092 085 040 083 088 085 m i t h . 045 I l i k e c h e 0000040 085 0a2 085 04b 025 e s e . 045 0000045 /home/jsmith $

Figure 9.17: The first od command displays the file personal.data in character format. The second command displays the same file in hexadecimal format, while the last command displays both formats.

Authority

The owner of a file or directory, or a user with *ALLOBJ special authority, can control authority to a file or directory in the IFS. By default, the owner of a file is the user who created the file. The owner can use Qshell's chown command or the CL Change Owner command (CHGOWN) to assign ownership to another user profile.

The terms group and group profile are frequently used interchangeably. A group may be any user profile that has a group identifier. Create a group by adding the group identifier to a new or existing user profile.

To assign a group ID to a user profile, use the GID parameter of the Create User Profile (CRTUSRPRF) or Change User Profile (CHGUSRPRF) CL commands as shown here:

CRTUSRPRF USRPRF(ADMINS) PASSWORD(*NONE) + INLMNU(*SIGNOFF) +TEXT('Administrators group profile') + JOBD(somelib/somejobd) GID(*GEN)

To assign a user to a group, use the GRPPRF parameter of CRTUSRPRF or CHGUSRPRF. In the following example, user JSMITH uses group permissions assigned to user ADMINS:

CHGUSRPRF USRPRF(JSMITH) GRPPRF(ADMINS)

By default, a file is not assigned to a group profile. The file's owner can use the Qshell's chgrp command or the CL Change Primary Group command (CHGPGP) to assign a group profile. The following command uses chgrp to assign file myfile.txt to group profile ADMINS:

chgrp ADMINS myfile.txt

This example also uses chgrp :

chgrp 104 myfile.txt

In this case, file myfile.txt is assigned to the group profile whose group ID is 104.

A file's group profile is shown just to the right of the owner's name in the long form of the ls command, as Figure 9.18 demonstrates .

ls -l *.txt -rwxrwxrwx 1 JSMITH 0 43 Feb 22 2002 ftpmodel.txt -rw-rw---- 1 JSMITH ADMINS 0 Oct 22 09:14 upper.txt

Figure 9.18: File upper.txt is assigned to group ADMINS. File ftpmodel.txt is not assigned to any group.

Permissions

There are five permissions, but for now, consider only three: read, write, and execute. (The other two are discussed later in this chapter.) Read, write, and execute mean different things for regular files and directories. The differences are shown in Table 9.6.

Sometimes a combination of permissions is required to perform a task. For example, to execute a Qshell script, the user must have both read and execute authority to the script file.

To display file permissions, use the ls command with the -l (letter "ell") option for files and the -l and -d options for directories. Permissions are shown in a ten-character file-mode field. The first character of the file mode indicates the type of file. Type symbols are listed in Table 9.7.

The other nine characters of the file mode are divided into three groups of three characters. As shown in Table 9.8, the first group of three characters is for owner permissions, the second group is for group permissions, and the last group holds permissions for all other users.

Read permission is indicated by an r in the first position of a group. Write permission is indicated by a w in the second position of a group. Execute permission is indicated by an x in the third position of a group. Permissions that are denied are indicated with hyphens.

Consider the ten-character file-mode field -rwxrw-r--. Since the first character is a hyphen, the file is a regular file. The three owner characters indicate the owner has read, write, and execute permissions. The group has read and write permissions, and other users have read permission only.

In Figure 9.19, the first ls command has just the -l option. Permissions are shown in the leftmost column. The second ls command, with the d option, shows permissions for the directory instead of each file. Without the d option, ls shows information about the files in the directory.

ls -l bin total: 32 kilobytes -rwxrw---- 1 JSMITH 0 21 Oct 28 18:38 axx -rwxrw---- 1 JSMITH 0 24 Oct 25 10:21 donde.qsh -rwsrw-rw- 1 JSMITH 0 0 Oct 24 16:32 one --wxrwx--x 1 JSMITH 0 20 Oct 24 16:34 one.qsh -rw-rw---- 1 JSMITH 0 0 Oct 24 16:31 upper.txt ls -ld bin drwxrwsrwx 2 JSMITTH 0 49152 Oct 28 18:35 bin

Figure 9.19: To see permissions for a directory, include the d option of the ls command.

Changing Permissions

To change permissions, use the chmod (Change Mode) command. You may specify permissions in two ways: absolute or symbolic . You can accomplish the same task with either mode, but the symbolic mode is probably the easier to work with.

Use symbolic mode when you want to modify some permissions and leave others as they are. Here is its syntax:

chmod permissions[,permissions] file

In symbolic mode, the permissions string consists of three parts . The first part is one or more letters that indicate which users are affected. These are listed in Table 9.9.

The second part is a one-character operator that indicates how the permissions are to be applied. These symbols are listed in Table 9.10.

The third part is made up of one or more characters, and indicates which permissions are being altered . These characters are listed in Table 9.11.

Figures 9.20 through 9.23 provide several examples illustrating the use of the symbolic mode of the chmod command.

ls -l myfile.txt -rw-rw-rw- 1 SMITH 0 0 Oct 24 18:03 myfile.txt /home/jsmith $ chmod a+x myfile.txt /home/jsmith $ ls -l myfile.txt -rwxrwxrwx 1 SMITH 0 0 Oct 24 18:03 myfile.txt

Figure 9.20: Grant execute authority for myfile.txt to all users.

ls -l myscript.qsh -rwxrwxrwx 1 SMITH 0 0 Oct 24 21:18 myscript.qsh /home/smith $ chmod -w,og-x myscript.qsh /home/smith $ ls -l myscript.qsh -r-xr--r-- 1 SMITH 0 0 Oct 24 21:18 myscript.qsh

Figure 9.21: Write permission is revoked for all users. File myscript.qsh is read-only. Execute permssion is also revoked for everyone except for the owner.

ls -l myscript.qsh -rwxrwxrwx 1 SMITH 0 0 Oct 24 21:18 myscript.qsh /home/smith $ chmod o= myscript.qsh /home/smith $ ls -l myscript.qsh -rwxrwx--- 1 SMITH 0 0 Oct 24 21:18 myscript.qsh

Figure 9.22: Since no value follows the equal sign, chmod revokes all permissions for users other than the owner and group.

ls -l myscript.qsh -rwxrwxrwx 1 SMITH 0 0 Oct 24 21:18 myscript.qsh /home/smith $ chmod o=g-w myscript.qsh /home/smith $ ls -l myscript.qsh -rwxrwxr-x 1 SMITH 0 0 Oct 24 21:18 myscript.qsh

Figure 9.23: Grant other users (those that are not the owner and not in the group) the same permissions that the group has, but do not give others write permission, regardless of whether the group has it or not.

In Figure 9.24, the ls command shows that file donde.qsh exists in the current directory, yet when the user tries to run the script, Qshell can't find it. The problem is that donde.qsh was created as a regular file, and by default, Qshell does not grant execute permission to regular files. After using chmod to grant execute permission, the user (the file's owner) can run the script.

ls donde.qsh donde.qsh /home/JSMITH $ donde.qsh qsh: 001-0019 Error found searching for command donde.qsh. No such path or directory. /home/JSMITH $ chmod u+x donde.qsh /home/JSMITH $ donde.qsh Script donde.qsh is running ...

Figure 9.24: By default, Qshell does not grant execute authority to regular files.

The absolute mode differs from symbolic mode in that absolute mode overlays all previous permissions. That is, you cannot add or remove just one or two individual permissions. Instead, you must replace all of them. Here is the syntax for the absolute mode of the chmod command:

chmod permissions file

To use absolute mode, specify a three- or four-digit octal number. The last (or only) three digits indicate owner, group, and others permissions, respectively. The numeric values of the permissions are listed in Table 9.12.

To grant more than one type of permission, add the values together. For example, to grant both read and write authority, use a six (the sum of four and two).

Figure 9.25 is a basic example of the absolute mode of the chmod command. It gives all users complete access to file myscript.qsh.

chmod 777 myscript.qsh /home/smith $ ls -l myscript.qsh -rwxrwxrwx 1 SMITH 0 0 Oct 24 21:18 myscript.qsh

Figure 9.25: This example uses absolute mode to grant execute permissions.

In Figure 9.26, everyone, including the owner, is granted permission only to read and execute the myscript.qsh file. That is, the file is read-only, even to the owner. To be able to modify the file, the owner must grant himself or herself write permission to it.

chmod 555 myscript.qsh /home/smith $ ls -l myscript.qsh -r-xr-xr-x 1 SMITH 0 0 Oct 24 21:18 myscript.qsh /home/smith $ cp arglist.qsh myscript.qsh cp: 001-0023 Error found opening file myscript.qsh. Permission denied. /home/smith $

Figure 9.26: File myscript.qsh is a read-only Qshell script.

The First Permission Byte

In addition to the read, write, and execute permissions, the s and S permission attributes are included for compatibility with PASEPortable Application Solutions Environment. PASE enables an iSeries machine to run AIX binaries.

Sometimes, users must be permitted temporary access to objects that, for security reasons, they normally are prohibited from using. OS/400 handles such situations by allowing programs to adopt the authority of their owners . Unix systems use a similar method. They permit programs to assume another user ID or group ID while they are running. The s symbol is derived from the setuid() and setgid() API calls. These API calls are typically used in the Unix system to implement the behavior similar to iSeries programs that adopt authority.

Use the s or S symbol in place of r , w , or x to set effective owner and/or group permissions when the file runs. Here is an example of the use of the s property:

ls -ld b* drwxrwsrwx 2 JSMITH 0 45056 Oct 25 17:02 bin

The group's execute authority is shown as s rather than x to indicate that the group permissions for the bin directory are assigned at execution time. If the file were not executable, an uppercase S would have been shown instead of the lowercase s .

The File Creation Mask

When you create a directory or regular file, OS/400 grants a default set of permissions. For directories, the permissions are 777 minus the file-creation mask. For regular files, the permissions are 666 minus the file-creation mask.

If the file-creation mask has a value of 000, then by default, all users (owner, group, others) have complete access to directories, and read and write access to regular files. This is a security hole that should be filled.

It is common in Unix installations to set the file-creation mask to 022, often by placing the umask command in the /etc/profile script. When a directory is created, permissions are set to 777 minus 022, or 755, which means that the owner has complete access to the directory, but everyone else has read and execute authorities only. When a regular file is created, permissions are set to 666 minus 022, or 644, which means that the owner has read and write permissions, but everyone else has read permission only. Another common umask value is 077, which grants complete authority to the owner, but no authority to group or others.

Here is the syntax of the umask utility:

umask [ -S ] mask

To display the setting of the file-creation mask, use umask without a mask argument. To view the mask in symbolic form, include the -S option. These two options are shown in Figure 9.27.

umask 022 /home/smith $ umask -S u=rwx,g=rx,o=rx

Figure 9.27: The file-creation mask is currently set to 022, which means that a file's owner receives all permissions by default, but other users receive only read and execute authorities.

To set the file-creation mask, include the desired mask as the first nonoption argument to umask . You may specify the permissions in absolute or symbolic form. For example, the following command sets the file-creation mask to 022:

umask 022

This prevents all users other than the owner from acquiring write permission when a new file is created.

Figure 9.28 shows the use of the symbolic form to set the file-creation mask to the equivalent of 022 in absolute form.

umask -S u=rwx,g=rx,o=rx /home/smith $ umask 022

Figure 9.28: Using symbolic form, the file-creation mask is set to the equivalent of 022 in absolute form.

Figure 9.29 also uses the symbolic form. In this case, the owner is given all permissions to new files. Both the group's and others' permissions are set to none.

umask -S u=rwx,go= /home/JSMITH $ umask 077

Figure 9.29: The file-creation mask is set such that the owner has all permissions to new files, but group and others have no permissions.

CCSIDs

CCSIDs (pronounced "see-sids") allow data to be stored in character sets that correspond to different collating sequences and national languages. Support for CCSIDs enhances the ability of the iSeries to act as a server and to exchange data with other systems.

The examples in this section illustrate some of the issues you might encounter when working with IFS files.

Displaying a File s CCSID Attribute

There are several ways to determine a file's CCSID attribute. The ls command displays CCSIDs if the -S option is specified:

ls -S [e-h]* 37 echoprocess.qsh 819 ftpmodel.txt 37 helpme 37 edity.txt 819 goodoleboys.txt

The file dump command, od , displays the CCSID if you specify the - C option. As shown, the CCSID is shown before the dumped contents:

od -C data.ascii data.ascii CCSID = 819 0000000 066151 067145 020061 005154 064556 062440 031012 0000016

The attr command, introduced with V5R2 and shown below, can also display or set a file's CCSID:

attr data.ascii CCSID 819

Setting the CCSID of an Existing File

You can use the setccsid utility to change the CCSID attribute of a file without changing the data in the file. You might need this capability, for example, after having received a file via FTP, as the system might not tag the file with the proper CCSID. As of V5R2, you can also use the attr utility to change a file's CCSID.

The setccsid and attr utilities are illustrated in Figure 9.30 and 9.31.

ls -S data.ascii 819 data.ascii /home/jsmith $ cat data.ascii line 1 line 2 /home/jsmith $ setccsid 37 data.ascii /home/jsmith $ cat data.ascii %> %> /home/jsmith $

Figure 9.30: The setccsid utility changes a file's CCSID, but not its contents.

attr data.ascii CCSID 819 /home/jsmith $ cat data.ascii line 1 line 2 /home/jsmith $ attr data.ascii CCSID=37 /home/jsmith $ cat data.ascii %> %> /home/jsmith $

Figure 9.31: You can use the attr command to change the CCSID attribute. As with setccsid, the contents of the file are unaffected.

File Creation

Many Qshell utilities create files. By default, Qshell tags new files with the current job's default CCSID. This is not always desirable, however. For example, a file that is to be accessed from networked PCs might need to be created in ASCII format.

Use the touch utility, shown in Figure 9.32, to create a file with the desired CCSID. In this example, the default CCSID for this job is 37. File "one" was created with CCSID 37 by default. The C option causes touch to create file "two" with CCSID 819. The S option causes the ls command to display each file's CCSID attribute

touch one /home/JSMITH $ touch -C 819 two /home/JSMITH $ ls -S1 one two 37 one 819 two

Figure 9.32: Use the touch utility to ensure that a file is created with the proper CCSID.

Environment Variable QIBM_CCSID

The QIBM_CCSID environment variable was added in V5R2. It specifies the CCSID with which new files are to be tagged. It also indicates the CCSIDs to use for certain translations of data. Table 9.14 lists utilities that use the QIBM_CCSID value.

The default value of QIBM_CCSID is zero, which tells Qshell and the utilities to use the job's default CCSID. Another special value is 65535, which means that no data translation is to be done.

Preserving the CCSID Attribute during Copy

By default, the cp utility changes the CCSID of an output file to that of the copied file. The effect of this process is demonstrated in Figure 9.32.

ls -1S data* 819 data.ascii 37 data.ebcdic /home/jsmith $ cat data.ebcdic line 1 line 2 /home/jsmith $ cp data.ebcdic data.ascii /home/jsmith $ ls -1S data* 37 data.ascii 37 data.ebcdic /home/jsmith $ cat data.ascii line 1 line 2

Figure 9.32: By default, cp changes the CCSID of the target file.

To preserve the output file's existing CCSID, use the -t (text) option, as shown in Figure 9.33.

ls -1S data* 819 data.ascii 37 data.ebcdic /home/jsmith $ cp -t data.ebcdic data.ascii /home/jsmith $ ls -1S data* 819 data.ascii 37 data.ebcdic /home/jsmith $ cat data.ascii line 1 line 2

Figure 9.33: Include the -t option when copying if you wish to preserve the target file's CCSID attribute.

The Iconv Utility

The iconv utility, which was added to Qshell at V5R2, reads one or more input files (or standard input), converts the data from one CCSID to another CCSID, and writes the converted data to standard output. Here is the syntax of iconv :

iconv -f fromCCSID -t toCCSID [file ]

The QIBM_CCSID environment variable and the C options discussed earlier in this section will usually be enough support for you when you're dealing with data in different code sets or languages. However, there might be a time when you have a file that is corrupted. Perhaps you want to simply translate some data. By sending the file over a network connection, or because of a bug in your application, you have written data to a file that is tagged with a different CCSID. When you look at a file that shows up as garbage, you might have a data or CCSID problem. The iconv utility might be able to help.

Figure 9.34 shows how you might detect and fix such a problem. Using a Qshell utility like cat , you see what looks like data corruption in a file named unicode.txt. Looking at the CCSID of the file, you see that it is set to a U.S. English CCSID of 37. Knowing that the file is a Unicode file that came from your Web application, you use iconv with a Unicode CCSID of 13488 as the from CCSID, and the default CCSID as the to CCSID.

cat unicode.txt + ? _ ? / % % ? ? _ > ? ? _ ? / ? ? > ' /home/jsmith $ ls -S 819 ascii.txt 37 unicode.txt /home/jsmith $ iconv -f 13488 -t 0 unicode.txt Now is the time for all good men to come to the aid of their country touch -C 13488 unicode2.txt /home/jsmith $ iconv -f 13488 -t 0 unicode.txt >> unicode2.txt /home/jsmith $ ls -S 819 ascii.txt 37 unicode.txt 13488 unicode2.txt /home/jsmith $ cat unicode2.txt Now is the time for all good men to come to the aid of their country

Figure 9.34: Use the iconv utility to do explicit data translations.

The data appears correct, so you know that you've got the CCSID correct. Use the touch utility with the C option to create a file with the correct CCSID, then use iconv again, this time redirecting the output to the newly created file. The iconv utility explicitly translates the data being read to the current CCSID of your session. Then, the system implicitly translates that redirected data to match the 13488 CCSID that you've tagged the file with. The result is that unicode2.txt contains the correctly tagged data.

File Comparisons

The file-comparison utility, cmp , does not allow for differences in CCSID unless you use the -t option. The - t option tells cmp to translate each input file to the job's CCSID before comparing. Figure 9.35 shows how you might use this option. Files "one" and "two" contain the same data, encoded under different CCSIDs. Without the - t option, cmp returns an exit status of 1 because it considers the files to be different. When the - t option is added to the command, cmp returns a status of 0, indicating that the two files contain the same text.

ls -S one two 37 one 819 two /home/jsmith $ cat one line 1 line 2 /home/jsmith $ cat two line 1 line 2 /home/jsmith $ cmp one two ; print $? one two differ: char 1, line 1 1 /home/jsmith $ cmp -t one two ; print $?

Figure 9.35: Use the t option when comparing files of different CCSIDs.

Summary

The Integrated File System includes all filing systems on the iSeries. It allows the iSeries to store data for which a relational database management system is not suitable. Since Qshell is derived from software that was designed to manage hierarchical file systems, Qshell provides a good interface to nondatabase data. Qshell includes utilities to manage all aspects of files, including creating, deleting, and renaming files and directories; displaying the contents of files; creating hard and symbolic links; controlling authorization to files; and setting the CCSID attribute.