Here's the command IBM should have given you but didn't.

In recent articles, starting with "Trying to Get a Handle on Your IFS?," we've seen how to automate the deletion of an IFS stream file when a file has not been used within a user-determined number of days. Rather than deleting a stream file, though, some companies would prefer to clear a stream file—similar to how the Clear Physical File Member (CLRPFM) command can be used to clear a database file member. Unfortunately, if you were to prompt generically for all commands that start with the letters CLR (that is, prompt for CLR*), you would find that there is not a Clear File (CLRF) or Clear Stream File (CLRSTMF) command on your system—or at least not one provided by the i operating system. For this reason, today's article will look at how to implement a CLRSTMF CL command.

Our CLRSTMF command will have one parameter: the path to the stream file to be cleared. In keeping with our previous commands, we'll start by defining prompt text for the command. Using the USERMSGF message file we've created in the past, add two message descriptions using the following commands.

ADDMSGD MSGID(FIL0001) MSGF(USERMSGF) MSG('Clear Stream File')

ADDMSGD MSGID(FIL0002) MSGF(USERMSGF) MSG('Stream file')

The command source, defined in member CLRSTMF of source file QCMDSRC, follows. 

CMD        PROMPT(FIL0001)                            

PARM       KWD(STMF) TYPE(*PNAME) LEN(1024) MIN(1) +  

             PROMPT(FIL0002)

One parameter, STMF, is defined. STMF is a required parameter and is defined as a path name with a rather arbitrary maximum length of 1024 bytes. To create the CLRSTMF command, specifying the program CLRSTMF as the command processing program (CPP), you can use the following CRTCMD command.                 

CRTCMD CMD(CLRSTMF) PGM(CLRSTMF) PMTFILE(USERMSGF)

The CPP source, stored in member CLRSTMF of source file QCLSRC, is shown below.

Pgm        Parm(&File_In)                                 

Dcl        Var(&File_In)    Type(*Char) Len(1024)         

Dcl        Var(&File)       Type(*Char) Len(1025)         

Dcl        Var(&Open_Flags) Type(*Int)                    

Dcl        Var(&Open_File)  Type(*Int)                    

Dcl        Var(&Errno_Ptr)  Type(*Ptr)                     

Dcl        Var(&Errno)      Type(*Int) Stg(*Based) +      

                            BasPtr(&Errno_Ptr)            

Dcl        Var(&Errno_Chr)  Type(*Char) Len(4)            

Dcl        Var(&MsgID)      Type(*Char) Len(7)            

Dcl        Var(&Write_Only) Type(*Int)  Value(2)          

Dcl        Var(&Truncate)   Type(*Int)  Value(64)         

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

             Value(x'00')                                        

ChgVar     Var(&File) Value(&File_In *TCat &Null)                

ChgVar     Var(&Open_Flags) Value(&Write_Only + &Truncate)        

CallPrc    Prc('open') Parm((&File) +                            

                            (&Open_Flags *ByVal)) +              

                       RtnVal(&Open_File)                        

If         Cond(&Open_File = -1) Then(Do)                        

           CallPrc Prc('__errno') RtnVal(&Errno_Ptr)             

           ChgVar Var(&Errno_Chr) Value(&Errno)                  

           ChgVar Var(&MsgID) Value('CPE' *Cat &Errno_Chr)       

           SndPgmMsg MsgID(&MsgID) MsgF(QCPFMSG) +               

                     MsgType(*Escape)                            

           EndDo                                                 

CallPrc    Prc('close') Parm((&Open_File *ByVal))

EndPgm                               

If your system is V6R1 or later, you can create the CLRSTMF program using the command shown below.

CRTBNDCL PGM(CLRSTMF)

If your system is on a release prior to V6R1, you can create the program using the two following commands.

CRTCLMOD MODULE(CLRSTMF)

CRTPGM PGM(CLRSTMF) BNDDIR(QC2LE)

There are several ways you might clear a stream file. The approach used in this article is to call the Open File API (open), which is documented here. The open API requires two parameters: a path to the file to be opened and a set of values that define how the file is to be opened.

The path parameter passed to the open API requires that the path value be null terminated. So, as we did in the DIR3 program of previous articles, the CLRSTMF program first concatenates a null byte (&Null) to the path value that is passed as the &File_In parameter to the program. This null-terminated value is then stored in variable &File.

The program then sets the &Open_Flags variable to indicate how we want to open the stream file identified by the &File variable. The &Open_Flags parameter is defined as a 4-byte integer value (that is, it's 32 bits in size) where individual bits of the integer value are associated with options on how the file is to be opened. As an integer variable, the individual bits can be addressed as numeric values. For instance a value of 1 sets the 32nd bit "on," a value of 2 sets the 31st bit "on," a value of 4 the 30th bit, and so on. For the open API, the 31st bit, when on, indicates that the file is to be opened for output only; and the 26th bit when on that the length of the file is to be set to zero if the file exists when the open API is called. Setting the file length to zero is essentially clearing the file. To address these bits, the program declares two variables: &Write_Only, which, with a value of 2, corresponds to the 31st bit of an integer; and &Truncate, which, with a value of 64, corresponds to the 26th bit of an integer variable. To set these two bits to "on" within the variable &Open_Flags CLRSTMF simply adds &Write_Only and &Truncate, storing the result in &Open_Flags.

Having set the necessary values for the &File and &Open_Flags parameters, CLRSTMF now calls the open API passing &File and &Open_Flags. The open API returns an integer value that is referred to as a file descriptor. When the open is successful, this file descriptor can be used to access the opened file. When the open fails, the API returns a file descriptor value of -1.

If the open is successful (that is, the return value &Open_File is not -1), the program simply closes the file using the Close File or Socket Descriptor API (close), documented here, and returns. As the file has been cleared and we have no desire to write to the file (at this time anyway), our task has been accomplished.

The close API defines one parameter, which is the file descriptor identifying the file to be closed (&Open_File). It's worth noting that files opened by the open API are not automatically closed (unlike database files referenced by DCLF), so the call to close is necessary in order to free up resources associated with the open file.

If an error is encountered when calling the open API (the &Open_File value returned by the API is -1), the CLRSTMF program sends an escape message to the user, describing the failure. If, for instance, you ran the command CLRSTMF STMF('gone') and the file 'gone' did not exist, escape message CPE3025 (No such path or directory) would be sent.

Identifying what message to send is accomplished by using the errno API (__errno). Note that that there are two leading underscores in the API name. The open API, like most of the IFS APIs in an error situation, will provide additional information on the error through an integer value known as errno. To access this value, you call the __errno API. The __errno API has no parameters and returns a pointer to the errno value. This value, when concatenated with the message prefix 'CPE' identifies a message within message file QCPFMSG, providing textual information describing the error.

The CLRSTMF program, when the open API returns a &File_Open value of -1, does this error-related processing:

• Calls the __errno API, which returns a pointer (&Errno_Ptr) to the most recent errno value
• Converts the numeric &Errno value to a 4-byte character form (&Errno_Chr). Note that &Errno is declared as being based on &Errno_Ptr.
• Concatenates the constant 'CPE' with &Errno_Chr, storing the result in variable &MsgID
• Sends an escape message where the message is identified by variable &MsgID

In the above case (not finding the file 'gone'), the errno value set by the open API is 3025, resulting in escape message CPE3025 being sent. Depending on how you want a given program to work, you could also use the 3025 errno value to condition error recovery rather than send an escape message. In the case of a CLRSTMF CPP, sending an escape message does seem appropriate though.

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 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 Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale