The CL Corner: Getting Additional IFS File Information

CL
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Let's look at some additional stat APIs.

 

In last month's column, "Dependency and Validity-Checking of Command Parameters," we looked at how a validity-checking program could be used to detect the use of conflicting parameter values when running the USEDIRPGM command. It had been my intent for this month's column to continue that discussion of validity-checking programs. However, some readers of this column have encountered a problem with the USEDIRPGM command processing program (CPP), so I'm moving up a topic that I had not planned on discussing for a while yet.

 

When initially implementing the USEDIRPGM command, in article "When Was an IFS File Last Used or Changed?," we used the Get File Information API stat, which is documented here. I chose to use the stat API as it provides quite a bit of useful information that can be easily utilized by CL developers on V5R4 through 7.1. This information, in addition to the date and time of last use and the date and time of last change (both currently used by USEDIRPGM), includes the size of the file, the CCSID of the file, etc. A problem with the stat API however, and unfortunately one that some users have encountered, is that it returns the size of the file as a 4-byte integer value. This use of a 4-byte integer limits the stat API to working with files that are 2,147,483,647 bytes or less in size. Files that are larger than this value will cause the stat API to return an error indicating that an overflow has been encountered.

 

There is, however, another implementation of the stat API named Get File Information (Large File Enabled), stat64, which is documented here. Rather than using a 4-byte integer value to return file size information, the stat64 API returns an 8-byte integer value. An 8-byte integer can represent a file size of up to 9,223,372,036,854,775,807 bytes—just a tad larger. The problem is, though, that CL didn't directly support 8-byte integer variables until 7.1 (which is why I initially used the stat API).

 

This lack of 8-byte integer support in earlier releases may, or may not, be a problem. The stat64 API itself has been available since V4R4, and if you don't need to access the file size (such as how the USEDIRPGM command is not currently utilizing the size), then only a few changes are needed to the DIR3 CPP.

 

The layout of the second parameter passed to the stat API, declared as &FileInfo in the DIR3 program, does need to be changed. When you're using the stat API, the three subfields used (&LstAccess, &LstDtaChg, and &ObjTyp) are defined as follows:

 

Dcl        Var(&FileInfo)   Type(*Char) Len(128)       

Dcl        Var(&LstAccess)  Type(*Int) +                                                 

            Stg(*Defined) DefVar(&FileInfo 25)        

Dcl        Var(&LstDtaChg)  Type(*Int) +                                                 

            Stg(*Defined) DefVar(&FileInfo 29)        

Dcl        Var(&ObjTyp)     Type(*Char) Len(10) +                                        

            Stg(*Defined) DefVar(&FileInfo 49)        

 

With the stat64 API, the location of the &ObjTyp subfield has changed. Bolding the one change in the DCL for &ObjTyp, the stat64 definition for the three subfields is this:

 

Dcl        Var(&FileInfo)   Type(*Char) Len(128)          

Dcl        Var(&LstAccess)  Type(*Int) +                                                 

            Stg(*Defined) DefVar(&FileInfo 25)           

Dcl        Var(&LstDtaChg)  Type(*Int) +                                                 

            Stg(*Defined) DefVar(&FileInfo 29)           

Dcl        Var(&ObjTyp)     Type(*Char) Len(10) +                                        

            Stg(*Defined) DefVar(&FileInfo 61)           

 

As we're now calling the stat64 API, rather than the stat API, we also need to change the CALLPRC command. Where we previously used…

 

CallPrc    Prc('stat') Parm(&Path &FileInfo) +                                           

            RtnVal(&Status)                               

 

…the program now needs to…

 

CallPrc    Prc('stat64') Parm(&Path &FileInfo) +                                         

            RtnVal(&Status)                               

 

Making these two changes to the DIR3 program source and recompiling the program then enables the USEDIRPGM command to run in "Large File Enabled" mode even on V5R4 and 6.1.

 

As in the earlier article, here is the entire definition for the stat64 &FileInfo parameter so that you can customize your own versions of USEDIRPGM. Remember, though, that you need to be on 7.1 in order to compile the DCLs for &Size, &AlcSiz, &RDev64, and &FSID64. If you do not need these variables, then you can be running on an earlier release by simply not including their declares.

 

Dcl        Var(&FileInfo)   Type(*Char) Len(128)                      

Dcl        Var(&Mode)       Type(*UInt) +                                                      

            Stg(*Defined) DefVar(&FileInfo 1)                        

Dcl        Var(&FileID)     Type(*UInt) +                                                      

            Stg(*Defined) DefVar(&FileInfo 5)                        

Dcl        Var(&UID)        Type(*UInt) +                                                      

            Stg(*Defined) DefVar(&FileInfo 9)                        

Dcl        Var(&GID)        Type(*UInt) +                                                      

            Stg(*Defined) DefVar(&FileInfo 13)                       

Dcl        Var(&Size)       Type(*Int)  Len(8) +                                               

            Stg(*Defined) DefVar(&FileInfo 17)                       

Dcl        Var(&LstAccess)  Type(*Int) +                                                       

            Stg(*Defined) DefVar(&FileInfo 25)       /* Last open   */

Dcl        Var(&LstDtaChg)  Type(*Int) +                                                       

            Stg(*Defined) DefVar(&FileInfo 29)       /* Last changed*/

Dcl        Var(&LstStsChg)  Type(*Int) +                                                       

            Stg(*Defined) DefVar(&FileInfo 33)         

Dcl        Var(&FSID)       Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 37)         

Dcl        Var(&BlkSiz)     Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 41)         

Dcl        Var(&NbrLinks)   Type(*UInt) Len(2) +                                         

            Stg(*Defined) DefVar(&FileInfo 45)         

Dcl        Var(&CP)         Type(*UInt) Len(2) +                                         

            Stg(*Defined) DefVar(&FileInfo 47)         

Dcl        Var(&AlcSiz)     Type(*UInt) Len(8) +                                         

            Stg(*Defined) DefVar(&FileInfo 49)         

Dcl        Var(&GenID)      Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 57)         

Dcl        Var(&ObjTyp)     Type(*Char) Len(10) +                                        

            Stg(*Defined) DefVar(&FileInfo 61)         

Dcl        Var(&ObjTypNul)  Type(*Char) Len(1) +                                         

            Stg(*Defined) DefVar(&FileInfo 71)         

Dcl        Var(&Rsv)        Type(*Char) Len(5) +                                         

            Stg(*Defined) DefVar(&FileInfo 72)      

Dcl        Var(&RDev)       Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 77)      

Dcl        Var(&RDev64)     Type(*UInt) Len(8) +                                         

            Stg(*Defined) DefVar(&FileInfo 81)      

Dcl        Var(&FSID64)     Type(*UInt) Len(8) +                                         

            Stg(*Defined) DefVar(&FileInfo 89)      

Dcl        Var(&NLink32)    Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 97)      

Dcl        Var(&VFS)        Type(*UInt) +                                                

            Stg(*Defined) DefVar(&FileInfo 101)     

Dcl        Var(&Rsv2)       Type(*Char) Len(22) +                                        

            Stg(*Defined) DefVar(&FileInfo 105)      

Dcl        Var(&CCSID)      Type(*UInt) Len(2) +                                         

            Stg(*Defined) DefVar(&FileInfo 127)     

 

In addition to the file size consideration, there is another limitation related to the USEDIRPGM CPP as it's currently coded. The CPP is using the Open Directory (opendir), Read Directory (readdir), and Get File Information (stat) APIs in order to, respectively, open a directory, access the contents of a directory, and then access information concerning files found within a directory. With each of these API calls, the CPP is working with directory and/or file names encoded in the job CCSID (or default job CCSID if the job CCSID is 65535).

 

For many companies, this may be sufficient, just as only supporting stream files up to 2,147,483,647 bytes in size might be sufficient. Other companies may, however, have directory and/or stream file names that span more than one language—for instance, an English-named directory containing Arabic, Greek, and Korean file names—and really need to be able to work with names encoded in multiple languages during one running of the USEDIRPGM command. For these situations, the i provides National Language Support (NLS)-enabled versions of the stat, stat64, opendir, and readdir APIs. The NLS-enabled versions of these APIs are QlgStat, QlgStat64, QlgOpendir, and QlgReaddir, respectively. We won't demonstrate the use of these APIs in this article, but I did want to make you aware of their existence.

More CL Questions?

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll try to answer your burning questions in future columns.

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7, V6R1

Bruce Vining

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 


MC Press books written by Bruce Vining available now on the MC Press Bookstore.

IBM System i APIs at Work IBM System i APIs at Work
Leverage the power of APIs with this definitive resource.
List Price $89.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  •  

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: