A: A CGI program is not limited to returning HTML. It can return any type of data. When you return data, you use the content-type HTTP header to designate the data type of the returned data. Apache is smart enough not to perform EBCDIC to ASCII translation when you return data that's not text.
In this article, I demonstrate how a CGI program can use the IFS APIs to read a file from the IFS and return it to a browser.
The IFS APIs can be used to read and write the standard input and output used with CGI programs. Although most articles and books tell you to use the QtmhRdStin() API to read standard input and the QtmhRdStout() API to write to standard output, these APIs are not the only methods of accomplishing these tasks.
You can also use file descriptors for the standard I/O streams. To do that, you should set the QIBM_USE_DESCRIPTOR_STDIO environment variable to Y. Though this setting appears unnecessary in Apache, it's required in other areas of the system, so for consistency, I feel that setting it is a good idea. When this variable is set, you can use the IFS read() and write() APIs to access standard input and output, respectively. To do so, use descriptor 0 for standard input and descriptor 1 for standard output. These descriptors do not need to be opened; Apache opens them before it calls your CGI program.
This method is ideal when you have a stream file in the IFS and you want to send it to a browser, because you can simply do the following:
D STDIN c 0
D STDOUT c 1
.
.
filename = '/home/klemscot/ifs_ebook.pdf';
pdf = open( %trimr(filename): O_RDONLY );
if (pdf = -1);
// handle error
endif;
//
// Specify the type of file and its filename.
// Note: change "inline" to "attachment" to let
// the user save it to disk.
//
text = 'Content-Type: Application/pdf' + CRLF
+ 'Content-Disposition: inline; filename='
+ %trimr(filename) + CRLF
+ CRLF;
callp write(STDOUT: %addr(text)+2: %len(text));
//
// Read the contents of the PDF file in binary
// mode and write it to stdout
//
len = read(pdf: %addr(buf): %size(buf));
dow len > 0;
callp write(STDOUT: %addr(buf): len);
len = read(pdf: %addr(buf): %size(buf));
enddo;
callp close(pdf);
To have Apache set the QIBM_USE_DESCRIPTOR_STDIO environment variable, you can insert the following into the Apache configuration under the library where your CGI program resides:
<Directory /QSYS.LIB/MYCGILIB.LIB>
Order Allow,Deny
Allow From all
SetEnv QIBM_USE_DESCRIPTOR_STDIO Y
</Directory>
If you change the content-type, you should be able to use the same technique to return other document types, such as Word or Excel documents, as well. You can return anything you like, as long as you pass back the correct content type.
Q: Is it possible to execute SQL statements from within a CL program?
A: Yes, you can run SQL statements from a CL program. To do so, you place your SQL statements in a source file member and then use command RunSQLStm (Run SQL Statements) to execute the statements in the member.
For example, suppose you wish to set field ProcFlag to value Y in all records found in file YourLib/YourFile. The following SQL statement accomplishes this:
Update YourLib/YourFile
Set ProcFlag = 'Y'
Simply create a source member with the above SQL statement and then in your CL program issue the following command:
You can run SQL statements in a batch job by submitting the RunSqlStm (Run SQL Statements) command. This command executes SQL statements stored in a source member. The source member can contain any valid SQL statements. Each SQL statement in the member must be separated by a semicolon.
Here's a simple example. Source member MySQL in file MySrc updates all the records in file InvMst and deletes selected records from file InvBal:
Update InvMst
set ImCls = 'AA',
ImTyp = '1';
Delete from InvBal
where IbQtyStk = 0;
To execute these SQL statements in batch with no commitment control, you would specify the following RunSqlStm command in the Cmd parameter of the SbmJob (Submit Job) command:
Sum character fields with decimals in SQL on the iSeries
SELECT sum(case when trim(mcm_ucop) = '' then 0 else cast(trim(mcm_ucop) as dec(11, 3)) end) as ucop, sum(case when trim(mcm_tadp) = '' then 0 else cast(trim(mcm_tadp) as dec(11, 3)) end) as tadp FROM mcm_
Field mcm_ucop and mcm_tadp are 15 characters : example 0000005187.570
I frequently have to create strings that consist of some known data and some variables. This requirement often leads me to write a rather complicated expression, such as the following one:
This type of expression can be a hassle to code. Mistakes (e.g., missing an apostrophe) are easy to make, and it's often unclear what the created string will be. To make this coding easier for myself, I wrote a utility named Parse. Using this utility, I can code the following:
The parse() procedure accepts one required parameter (the base string, containing substitution variables) and up to nine additional optional parameters (the substitution values themselves). The base string can contain up to nine separate substitution variables, in the form &n, where n is a number from 1 to 9, which refers to a substitution value parameter. A substitution variable can occur multiple times in the base string.
In the preceding example, the &1 variable is replaced with the first optional parameter, which is %trim(Lib). The &2 substitution variable is replaced with %trim(File), and so forth.
All the parameters are defined as pointers, with the OPTIONS(*STRING) keyword, which means that you can pass either a hard-coded string or a variable to the parse() procedure. Note that if a variable is passed, trailing blanks are included unless it's defined with the VARYING keyword or is passed with the %trim() or %trimr() built-in function (BIF).
Some examples of using parse() might be as follows:
D Base C 'My &1 is &2.'
D Type S 10A Inz('life')
.
.
/free
// Example 1: Simple string replacement (1)
String = parse( Base : 'name' : 'Rory Hewitt' );
// Result 1: String = 'My name is Rory Hewitt.'
// Example 2: Simple string replacement (2)
String = parse( '&1&3&2 &1&4&2' : '(' : ')' : 'value1' 'value2' );
// Result 2: String = '(value1) (value2)'
// Example 3: Passing an untrimmed variable
String = parse( Base : Type : 'good' );
// Result 3: String = 'My life is good.'
// Example 4: Passing a trimmed variable
String = parse( Base : %trim( Type ) : 'good' );
// Result 4: String = 'My life is good.'
/end-free
If a substitution value parameter that lacks a corresponding substitution variable in the base string is passed, it is simply ignored. In the following example, the last parameter is def, but it's ignored because the Base string has no &3:
D Base C 'My &1 is &2.'
.
.
String = parse( Base : 'job' : 'worker bee' : 'def' );
// Result: String = 'My job is 'worker bee'.'
If a substitution variable is found in the base string but has no corresponding substitution value parameter, it remains in the base string. In the following example, the result will contain &2 because I did not pass enough parameters to supply a replacement for the &2 variable:
D Base C 'My &1 is &2.'
.
.
String = parse( Base : 'life' );
// Result: String = 'My life is &2.'
Substitution variables (e.g., &3) passed in substitution value parameters are not themselves parsed. So in the following code, &3 is simply treated like any other substitution value:
D Base C 'My &1 is &2.'
.
.
String = parse( Base : '&3' );
// Result: String = 'My &3 is &2.'
However, you could use that string as input to a subsequent call to parse() where it would be used. In this next example, the first call to parse() simply replaces the substitution variable &1 with the substitution value &3; when parse() is called a second time, &3 is now a substitution variable in the base string, so it's replaced:
D Base C 'My &1 is &2.'
.
.
String = parse( Base : '&3' );
// Result: String = 'My &3 is &2.'
String = parse( String : 'ignored' : 'Rory Hewitt' : 'name' );
// Result: String = 'My name is Rory Hewitt.'
Using the parse() procedure makes seeing what the eventual command string will be easier. My original CRTPF example code is much simpler to understand when using parse() than when using lots of string concatenation, because the base string looks very similar to the eventual command. In fact, in addition to the base string being hard-coded or defined as a constant in the D-specs or in a compile-time array, it could be retrieved from a file at runtime, thus allowing you more flexibility when creating command strings for different environments or outputting form letters or whatever.
Creating Parse()
Because parse() is simply a procedure, I included no information about how to compile it. I suggest that you either put it into an existing module (perhaps one that already contains similar string-handling procedures) or create a new one, which you would then bind into a service program containing other "generic" procedures, such as string-handling and numeric conversion. Any program that needs to call parse() must /COPY in the PARSE_P copybook.
You can download the parse() utility from the following link:
You won't often find me extolling the virtues of an error message. After all, I pride myself on writing proper code. I don't want to receive errors. However, there's one error message that I think is one of the best enhancements ever made to the RPG language: RNQ0103 "Target for a numeric operation is too small to hold result."
Until recently, I thought that you could get this message only if you did your math in an expression, such as those used on an EVAL opcode. I thought that the old-style math opcodes (e.g., ADD, SUB, DIV, MULT) could not produce this error. Today, I discovered that they can.
The trick is the Truncate Numeric (TRUNCNBR) compiler option. You can specify TRUNCNBR(*NO) on the CRTRPGMOD, CRTBNDRPG, or H-spec to tell the compiler that you want the program to fail with an error if a value is too large to fit in the receiver variable. For example:
CRTBNDRPG PGM(myProgram) TRUNCNBR(*NO)
Why do I like this option so much? I like it because it prevents errors. Consider a report that lists all the payments that your accounting department needs to collect from customers. It totals all the invoices issued to each customer and subtracts all the previous payments to get the current balance. What happens if the total of invoices is too large for the receiver variable? You might not know that the customer owes anything! The customer might get away with short paying by thousands of euros!
When you specify TRUNCNBR(*NO), the program can send an error message. If you've written a *PSSR to trap errors, that *PSSR can notify someone that a problem exists, so that they can take corrective action. If you don't use a *PSSR or some other technique that monitors for errors, the program crashes and the user calls you for help.
SystemiPortal.com, which provides a System ispecific resource directory and in-depth search tools for news, technical information, forums, blogs, wikis, and more. The site is part of the new iSociety communitybuilding initiative.
Perhaps the biggest benefit to be derived from free form is one of legibility. In free form you may use the positioning of the code to help clarify the structure.
Figure 1 shows a comparison between a snippet of code written using extended Factor 2 and the exact same code in free form. The use of free form makes it easy to see the structure of the nested IFs and the IF/ELSE. Actually, the code shown in Figure 1 was converted to free form using an option in the Remote System Explorer (RSE) LPEX editor in Websphere Development Studio Client (WDSC) Source/Convert All to Free Form.
Increased legibility is also provided by the fact that you have more space on a line for code. This is especially useful when you start using qualified data structures, which lends to longer names on a line since field names must be qualified with the data structure name.
Of course, it is possible to write hard to read (if not illegible) code in free form but that can be said of whatever coding structure you use. I can write code as badly in free form as I do in fixed form but, on the other hand, I can write code that is a lot easier to read in free form than it is in fixed form.
Unsupported operation codes
Not all operation codes are supported in free form. Some operation codes have been replaced by Built-in Functions (BIFs) (e.g. %SUBST, %OCCUR, %XLATE) but other operation codes do not have a direct equivalent. The more obvious of these are the standard ADD, SUB, DIV, MULT, MOVE and MOVEL operation codes. Just as with extended Factor 2, these operation codes may be emulated with the EVAL operation but you must remember that EVAL is not as forgiving as the fixed format operation codes.
Numeric overflow is not tolerated by EVAL so you will receive a run-time error if you fill a numeric field as opposed to the value wrapping around to zero.
There is no direct equivalent of the MOVE operations; you must use BIFs (%CHAR, %DEC, %DATE, *INT) is you need to move data between fields with different data types and you may need to use %SUBST if you need to move data between fields of different lengths. A lot of people see this as a problem but I actually see it as an advantage in that it leads to self-documenting code. Compare the two lines of code shown in Figure 2. In the fixed format line you must be familiar with the definition of the two fields to understand what the MOVEL operation is achieving whereas the free form equivalent is self explanatory; it may not be as easy to code but it is easier to understand when you read it.
Figure 1 shows a comparison between a snippet of code written using extended Factor 2 and the exact same code in free form. The use of free form makes it easy to see the structure of the nested IFs and the IF/ELSE. Actually, the code shown in Figure 1 was converted to free form using an option in the Remote System Explorer (RSE) LPEX editor in Websphere Development Studio Client (WDSC) Source/Convert All to Free Form.
It is now possible to have a program that consists of fixed format, extended Factor 2 and free form RPG -- not a pretty site and something to be avoided if possible.
Extended Factor 2 operations will convert directly to free form but you need a third-party tool (or write one yourself) if you want to convert the unsupported operation codes to free form.
Only FREE
shows the traditional code for defining a key list to be used with a file where the key consists of a number of fields.
shows how a key list may be emulated in the D specs. An externally defined data structure is defined using the optional parameter of *KEY on the EXTNAME key word to indicate that only key fields from the external file are to be included in the data structure. This data structure is then used as an argument for the %KDS BIF on the CHAIN operation. The %KDS BIF may only be used in free form. This is slightly better than a key list in that the %KDS keyword makes it clear that a data structure is being used to define the key.
But Figure 7 shows the preferred way to access a record using multiple key fields. Simply provide the list of key fields to be used directly on the operation code. You may even use a literal and/or an expression as one of the key fields!
Another new language feature that is geared towards free form is the XML-INTO operation code (introduced in V5R4). You must use free form if you want to use either the E or H extender with XML-INTO since the length of the operation code and the extender is eleven characters as opposed to the ten allowed for the operation code in fixed form and extended Factor 2.
Netwerkkabels zijn kant-en-klaar te koop, maar vaak slechts beschikbaar in enkele maten en bovendien erg duur. Goedkoper is het om zelf kabels te maken. We laten u zien hoe u te werk moet gaan.
Voor het maken van kabels dient u 'UTP Ethernetkabel' in huis te halen. UTP staat voor Unshielded Twisted Pair en wordt gebruikt voor een netwerk op basis van een ster-topologie: vanuit één plaats, zeg maar de centrale netwerkswitch, vertrekken meerdere UTP-kabels naar de verschillende vertrekken in uw huis.
Er bestaan verschillende categorieën UTP-kabels, waarbij vooral de kwaliteit en de ondersteunde snelheden een rol spelen. Zo is UTP van categorie 5 prima geschikt voor netwerksnelheden tot 100 Mbit/s. Wilt u sneller gaan, dan investeert u bij voorkeur in UTP-kabels van categorie 6. Daarmee zijn snelheden tot 1.000 Mbit/s mogelijk.
Let er op dat de totale afstand tussen twee netwerkapparaten in een Ethernet-netwerk nooit meer dan honderd meter mag bedragen. Houd de afstand dus zo kort mogelijk, vooral omdat langere kabels een negatieve invloed hebben op de snelheid. Kabels van minder dan een halve meter zijn echter evenmin aan te raden.
Stap 1: Materiaal verzamelen Voor we aan de slag kunnen gaan, hebben we enkele zaken nodig. Ten eerste: een speciale krimptang. Een dergelijke tang wordt gebruikt om de netwerkstekkers op de netwerkkabel te drukken. Koop een krimptang die overweg kan met RJ45-stekkers. Er bestaan namelijk ook tangen die speciaal bedoeld zijn voor telefoonkabels (type RJ11). Natuurlijk hebben we ook nog RJ45-stekkertjes nodig: twee per kabel.
Voor de aanschaf van netwerkkabel moet u vooral uitkijken naar aanbiedingen voor bulkhoeveelheden - die zijn nu eenmaal goedkoper. Meestal komen deze in de vorm van een grote kartonnen doos met enkele honderden meters netwerkkabel. De doorsnee computerwinkel zal zoiets echter niet in voorraad hebben. Een kijkje op de veilingen van eBay of Marktplaats kan hier van pas komen (zoek op de term 'UTP'): zo vonden wij op eBay driehonderd meter UTP-kabel (categorie 5) voor zestig euro.
Stap 2: knippen en strippen Knip met behulp van een scherp mesje of een schaar de netwerkkabel op de gewenste lengte. Verwijder vervolgens drie centimeter van de buitenste plasticlaag van de kabel. U kunt daarvoor een speciale striptang gebruiken, maar met een stanleymesje kan het ook. Als de kabel eenmaal gestript is, ziet u binnenin vier gekleurde draadparen. Trek de draadparen los, zodat er acht aparte en vrij te bewegen aders vrijkomen.
Stap 3: kleurvolgorde Voor een goed werkende netwerkkabel moeten de gekleurde aders in de juiste volgorde naast elkaar gezet worden. Er bestaan hiervoor twee kleurenstandaarden, EIA/TIA 568B en 568A. Voor datacommunicatie maakt het in principe niet uit welke u gebruikt, zolang u maar consequent dezelfde standaard hanteert.
Wij kiezen voor de 568A-standaard, en dat betekent van links naar rechts de kleuren groen/wit, groen, oranje/wit, blauw, blauw/wit, oranje, bruin/wit en bruin (klik op de afbeelding bij dit artikel voor een schema). Zorg ervoor dat de aders perfect naast elkaar liggen, zonder kronkels; duw er eventueel met uw duim op om alles mooi glad te krijgen. Is dit gelukt, knip dan de bovenkant van de aders recht af met een schaar, zodat u zo'n twee centimeter van de blootliggende aders overhoudt.
Stap 4: inschuiven en krimpen Nu schuiven we de gekleurde aders in de RJ45-stekker. Let op de oriëntatie van de stekker: zorg dat het lipje naar beneden is gericht. Schuif er nu heel voorzichtig de acht aders in en duw deze aan tot aan de kop van de RJ45-stekker.
Neem nu de krimptang. Plaats de RJ45-stekker in de krimptang en druk deze aan. Voorzie vervolgens het andere uiteinde van de kabel op exact dezelfde manier van een RJ45-stekker, en uw netwerkkabel is klaar voor gebruik.
APIs by Example: Retrieve Job Description Information API
Job descriptions play a very important role in work management on the i5. Whenever an interactive, batch, autostart, or prestart job begins its life, a number of significant job attributes are retrieved from the job description assigned to that job. As a consequence, job descriptions need to be carefully created, managed, and assigned, or unexpected and serious problems might be the outcome.
As programmers, we can help avoid these problems by writing utilities that make the system administrator's job easier. To write utilities that work with job descriptions, understanding the Retrieve Job Description Information (QWDRJOBD) API is helpful.
For example, if a library contained in the initial library list of a job description is deleted, and that job description is assigned to a user profile, the user profile in question can no longer sign on to the system but instead receives the error message "CPF1113 Library in initial library list not found." To help avoid such situations, and provide a working example of the QWDRJOBD API, I've written the Work with Referenced Job Descriptions (WRKREFJOBD) command.
The WRKREFJOBD lets you find and list all job descriptions referenced by specific objects on your system, before deleting or renaming these objects. From the resulting list panel, you then have various options to perform against the selected job descriptions, such as change, display, or delete the job description.
The WRKREFJOBD utility also provides yet another opportunity to demonstrate how powerful it is to combine list and retrieve APIs. In this example, I use the Open List of Objects (QGYOLOBJ) API to create a list of job descriptions and subsequently, for each returned qualified job description name, I use the QWDRJOBD API to retrieve the attributes of the job description. Using this information, I then evaluate the specified selection criteria and decide whether the job description should be included in the Work with list panel.
You can specify all combinations of job description and library special values to narrow your search to specific or generic job descriptions in various libraries. To list all job descriptions in library QSYS that have a user profile specified, run the following command:
WRKREFJOBD JOBD(QSYS/*ALL) USRPRF(*ANY)
You also have an option to define the relationship between multiple selection criteria. If you specify an OR relationship, all job descriptions meeting just one of the criteria are included in the list. Specifying an AND relationship includes only the job descriptions meeting all the specified criteria.
The preceding command leads to the display of the following list panel (optionally, you can have the list printed instead):
The list panel offers three alternate views, all in all displaying each job description's user, print device, initial library list flag, partial request data, job and output queue as well as text description. Cursor-sensitive help text is provided for the list panel and the command to explain all details.
In case you are wondering how job descriptions are assigned to the different job types that I've mentioned, here's a brief overview:
Interactive jobs pick up the job description from the work station entry that they are signing on through. By the default special value *USRPRF, the work station entry points to the signing-on user profile's job description, as you can see on the partial command prompt of the Add Workstation Entry (ADDWSE) command:
Add Work Station Entry (ADDWSE)
Type choices, press Enter.
Subsystem description . . Name
Library . . . . . . . . *LIBL Name, *LIBL, *CURLIB
Work station name . . . . Name, generic*
Work station type . . . . *ALL, 3179, 3180, 3196...
Job description . . . . . *USRPRF Name, *USRPRF, *SBSD
Library . . . . . . . . Name, *LIBL, *CURLIB
To inspect how your system is set up, run the Display Subsystem Description (DSPSBSD) command against your interactive subsystem and select option 4 (Work station name entries) and 5 (Work station type entries). From each resulting panel, you can specify option 5 for the entry that you want to display.
Batch jobs rely on the Submit Job (SBMJOB) command's job description (JOBD) parameter to locate the job description under which the job should run. By default, this parameter also points to the special value *USRPRF. In this context, *USRPRF refers to the user profile specified on the SBMJOB command's user (USER) parameter, which by the default value *CURRENT points to the user profile running the SBMJOB command. So if the default values are used for these two parameters, the submitting user profile is the origin of the job description for the submitted batch job.
For prestart jobs and autostart jobs, the job description is named directly on the Add Prestart Job Entry (ADDPJE) and Add Autostart Job Entry (ADDAJE) commands, respectively. In both cases, special values can also be used to define the job description parameter. Diving deeper into i5/OS work management is beyond this article's scope, but I have collected a number of links providing useful information for learning more about this topic:
This APIs by Example includes the following sources:
CBX161 -- Work with Referenced Job Descriptions - CCP
CBX161E -- Work with Referenced Job Descriptions - UIM Exit
CBX161H -- Work with Referenced Job Descriptions - Help
CBX161P -- Work with Referenced Job Descriptions - Panel Group
CBX161X -- Work with Referenced Job Descriptions
CBX161M -- Work with Referenced Job Descriptions - Build Command
To create all these objects, compile and run CBX161M. Compilation instructions are in the source headers, as usual.
Q: I'm new to ILE, and I'm not sure whether I bound my program to a *MODULE or to a *SRVPGM. How can I find out how it was bound to verify that I did it correctly?
A: Whenever you're new to something, it's always good to have a way to check the results of what you did, to ensure that it all worked the way you expected it to. ILE is no different.
The Display Program (DSPPGM) command tells you which modules were copied into your program, as well as which service programs your program references. For example:
DSPPGM PGM(mylib/mypgm)
The first screen is helpful for checking that your program has the correct activation group, as well as adopted authority settings, and so forth. It looks like this:
These are the modules that you listed in the MODULE keyword of the Create Program (CRTPGM) command, or that were included as *MODULE type entries in a binding directory. If you used a binding directory, only the modules actually used are listed here.
If you like, you can key the number 5 next to each module to view more information about it. This option tells you the source file and member from which the module was created, the date and time that source member was last modified, and lots of other stuff.
When you're done viewing the details of the module(s), you're returned to the screen where it listed them. If you hit the Enter key once again, you see the service programs referenced. Here's what that screen looks like:
Display Program Information
Display 4 of 7
Program . . . . . . . : MYPGM Library . . . . . . . : MYLIB
Owner . . . . . . . . : GOODGUYS
Program attribute . . : RPGLE
Detail . . . . . . . . : *SRVPGM
Type options, press Enter.
5=Display
Service
Opt Program Library Signature
QRNXIE QSYS D8D9D5E7C9C540404040404040404040
QRNXUTIL QSYS D8D9D5E7E4E3C9D34040404040404040
QLEAWI QSYS 44F70FABA08585397BDF0CF195F82EC1
UTILR4 *LIBL E4E3C9D3D9F4E2E3C1E3C9C340404040
Bottom
F3=Exit F4=Prompt F11=Display character signature F12=Cancel F17=Top
F18=Bottom
The first three service programs listed (the ones in library QSYS) are automatically bound to all ILE RPG programs. I didn't have to specify them in a binding directory or on the CRTPGM statement. They're always included automatically because they contain routines that the RPG runtime environment needs to run an RPG program.
The last one (UTILR4) is one of my own service programs. Because I found it here in the service programs section and not on the modules screen, I know that I'm calling the service program's routines instead of calling its modules directly. That's important, because I don't want to have to rebind all my programs if I make a change to the UTILR4 service program.
The DSPPGM command makes verifying that you created your *PGM object with the right parameters easy. When you want to check a *SRVPGM object to see which modules or other service programs it references, you can use the Display Service Program (DSPSRVPGM) command. It works almost exactly the same as DSPPGM, except that it shows the details of a *SRVPGM object instead of a *PGM object.
When you want to control how long journal receivers are available online, you will want to "age" the receivers. For example, if you want to keep five days' worth of transactions online, you can either manually delete the old receivers or run the command presented this month.
The Remove Journal Receivers (RMVJRNRCV) command lets you age the receivers and optionally connect the journal to a new receiver.
You can run this command against all your journals, including QAUDJRN, to perform an intelligent deletion of old receivers.
The command performs a clean-up process against the specified journal's receiver directory. You can specify the number of journal receivers to retain, the number of days (since detachment), or a combination of both. The force parameter controls whether the journal receivers should be saved to be eligible for deletion and, for remote journals, whether replication should occur. Optionally, you can have the CHGJRN command run to change the journal receiver (before directory clean up). I've also included the Sequence option so you can ensure that the journal entry numbering is continued, regardless of the current default value of the CHGJRN command.
For more details about command parameters and command usage, refer to the help panel group.
The following source code is included. As always, check the source code headers for compile instructions and additional documentation.
Journals are used by i5/OS for many purposes, such as
recording before and after images of database record inserts, changes, and deletions
recording security-related events like authority failures, invalid sign-ons, changes to system values, and deletion of objects
recording user-defined events
If you are curious about how many journals exist on your system, you can run the command WRKJRN *ALL/*ALL. There are a multitude of journals; most are used for recording database changes. IBM supplies many of the journals, and others are user created. One of the issues that you run into with journals is that the associated journal receivers can often require significant disk space. The journal receiver is actually the storage area for the data collected through the journal.
How Big Are My Journal Receivers?
To display all your current journal receivers and to get a listing of the size of each receiver, you can use the following command:
Or you can choose the OUTFILE option and place the output in a database file. You can then use a query tool to list the receiver name (ODOBNM), the library name (ODLBNM), and the receiver size in bytes (ODOBSZ). I think if you add up the size of all your journal receivers, you'll be surprised at the amount of disk space used to hold all journaled data. Some of you will be appalled.
You will want to delete the journal receivers that are no longer needed. To identify those that are not needed, look at the detach date and whether the receiver has been saved. You determine how many days of receiver data you need by considering your requirements for reporting, freeing disk space, and forensic research on the receiver data.
How to Call an API Without Worrying About the 64 KB Limit
Q: I want to return information about the indices built over a physical file. I'm using the Retrieve Member Description (QUSRMBRD) API to do that. One of our files has more than 70 logical files built over it, and each index needs 2,176 bytes of space. If my math is correct, that means I need 217,600 bytes! Is there a good way of overcoming RPG's 64 KB limitation? In the future, I want to be ready to handle even more indices, should they be needed!
A: The QUSRMBRD API, like many APIs, can tell you how much space it needs to return all its results. Rather than use a variable whose size must be known at compile-time, I suggest using dynamic memory allocation. That way, you can ask the API how much space it needs and then tell the operating system that you need exactly that much memory. Using this technique, you won't have to worry about RPG's 64 KB limitation.
The QUSRMBRD API when called with format MBRD0400 returns an array of information about the indices of a file. At the start of MBRD0400, there's information about how much space the API needs to return a complete array. The start of the format looks like this:
D MBRD0400 ds qualified
D based(p_RcvVar)
D BytesRtn 10I 0
D BytesAvail 10I 0
D Count 10I 0
D Offset 10I 0
As you can see, I based this data structure on a pointer. I ask the system to allocate enough memory to store this minimal data structure, and I pass that to the API. Of course, the API can't fit any indices in the preceding data structure, but it fills in the BytesAvail variable, and that variable tells me how much memory I need if I want the whole thing.
The first time through the loop, nothing has yet been allocated to p_RcvVar, so it is set to *NULL. When this happens, I use the %ALLOC built-in function (BIF) to ask the operating system for enough memory for the minimal data structure.
The second time through the loop, I release the memory that the operating system previously provided, and I ask for enough memory to get everything the API has to offer and call the API again.
In almost all cases, the program runs through the loop only twice. If someone manages to add a new index between the time I call %ALLOC and the time I call the API, I end up looping a third time to expand the memory again. In the end, though, I get the whole thing.
After you do that, you can use the same pointer logic that you typically use with offsets provided by APIs to loop through the returned data and do something with it. For example:
D InxDS DS Based(p_InxDS)
D qualified
D LibNam 258A Varying
D FilNam 258A Varying
D MbrNam 258A Varying
D CstTyp 11A
D 9A
D InxVld 1A
D InxHld 1A
D 6A
D CrtDTM 14A
D RBldDTM 14A
D UseDTM 14A
D SttDTM 14A
D UseCnt 20I 0
D SttCnt 20I 0
D Stt2Cnt 20I 0
D Keys 20I 0
D Size 20I 0
D Key1Unq 20I 0
D Key2Unq 20I 0
D Key3Unq 20I 0
D Key4Unq 20I 0
D RBldSec 10I 0
D DlyKeys 10I 0
D OvFlCnt 10I 0
D CdeSiz 10I 0
D LFRdRqs 20I 0
D PFRdRqs 20I 0
D 56A
D Sparse 1A
D DrvKey 1A
D Partnd 1A
D Maint 1A
D Recvry 1A
D Type 1A
D Unique 1A
D SrtSeq 1A
D SrtLib 10A
D SrtNam 10A
D SrtLang 3A
D SrtWgt 1A
D PagSiz 10I 0
D KeyLen 10I 0
D KeyCnt 10I 0
D 82A
D KeyLst 1024A Varying
.
.
for ix = 1 to MBRD0400.Count;
p_InxDS = p_RcvVar + MBRD0400.Offset +
(ix-1) * %size(InxDS);
// do something with the data in the InxDS
// data structure here.
endfor;
dealloc p_RcvVar;
Don't forget to use the DEALLOC opcode at the end of the program to return the allocated memory to the system. (If you forget, it won't be released until the activation group ends.)
Q: I'm writing an RPG program that has a numeric field defined as "5P 2". If it contains a value such as 3.00, I want to move it to a character field and display it without trailing zeroes. However, if the decimal has a value such as 3.01, I want to display it as is. How can I do this?
A: There isn't an edit code or edit word that strips trailing zeroes, so you have to write a bit of program logic.
The basic premise of this code is to check the variable to see whether anything is in the decimal places. If it is, move them to the numeric field. If not, strip them before you move them. The following code works in V5R1 or later:
D mynum s 5 2
D char s 7A
.
.
if %dec(mynum:3:0) = mynum;
char = %char(%dec(mynum:3:0));
else;
char = %char(mynum);
endif;
The %DEC() built-in function (BIF) is used to convert the number to a 3,0. In other words, it's the same field, but without the two decimal places. If it still has the same value after the decimal places have been stripped, you know that those decimal places were zero. Therefore, you can format this 3,0 field into the character variable.
If stripping the decimal places causes the value to be different, then a value must've been in those decimal places, so they're kept in when formatting the string
Q: I need to write a CL program that processes the contents of an IFS directory. I need it to allow wildcards, both that exist and that don't exist. For example, I want to process *.csv in the directory. For all files that end in csv (and match the pattern), I want to copy them to database files and move them to a different place in the IFS. For those that don't end in csv, I want to move them to a different place in the IFS. The wildcard pattern can be different on each call to my program. How can I do that in CL?
A: In the May 19, 2005, issue of this newsletter, I provided some CL commands that you can use to read the contents of an IFS directory. After these commands are installed on your system, you can read a directory as easily from CL as you can from any other language.
In this article, I enhance those commands to meet your needs. I provide the source code for the CL commands and a service program that enables the same support from RPG, and I demonstrate how to use them.
The original article from the May 19, 2005, issue of this newsletter let you pass a regular expression when opening a directory. A regular expression is a pattern-matching scheme, similar to the wildcard in your example but more powerful.
The problem with the original article is that it provides only the file names that match the regular expression, and not those that don't match. I've extended the utility by adding parameters to "reverse" the regular expression. When you tell the utility to reverse the regular expression, instead of returning only the files that match, the utility returns only those that don't match.
For example, here's a CL program that uses my commands to read all the files in the /data/dir directory that end in CSV:
For the sake of demonstration, I use the SNDPGMMSG command to print the file name of each file as a *DIAG message that you can view in your job log.
Notice that I provide a regular expression of CSV$ to the OPENDIR command. The $ character means that the pattern is matched only at the end of each file name, so this finds all files that end in CSV. The regular expression matching that OPENDIR uses is case-insensitive, so this matches files that end in CSV, Csv, csv, and any other combination of upper case and lower case that you can think of.
There's also a REWINDDIR command in my utility. When you run that command, it moves back to the start of the directory list and lets you read it again. This new revision of the utility adds a REVERSE parameter to the REWINDDIR command. If you tell it to reverse, when you read the directory again, it gives you the files that don't match the regular expression instead of the ones that do.
Here's another example. This time, I read the directory list twice: The first time, I retrieve all the files that end in CSV, and the second time, I retrieve all those that do not:
In the preceding sample, the code first reads every file that matches the pattern CSV$, just as the previous example did. After it has finished reading through the directory the first time, it uses the REWINDDIR command (in red) to tell the system to read the directory again. This time, however, it specifies REVERSE(*YES), which tells it to retrieve the opposite files (i.e., those that do NOT match CSV$), so I get everything that doesn't end in CSV.
In blue, I put the code that prints the file names to the job log. In your program, you need to replace this blue code with the code that moves your files to the appropriate directories. In the first section, you process CSV files, so you need to move your files to the correct directory for CSV processing and copy them to database files. In the second section, they are non-CSV files, so you need to move them to the alternate directory.
Under the covers, these commands work by calling subprocedures in an ILE RPG service program. If you're not an RPG programmer, rest assured that after you compile this utility on your system, you won't need to know anything about the RPG code. You can use the CL command wrappers that I demonstrated earlier from your ILE and OPM CL programs.
However, if you need the same sort of support from RPG, you might find calling the subprocedures directly handy. For example, here's a program written in RPG and very similar to the preceding CL programs:
H DFTACTGRP(*NO) BNDDIR('IFSDIR')
/copy ifsdir_h
D d s 10I 0
D file s 640A
D msg s 52A
/free
*inlr = *on;
d = IFS_opendir('/data/dir': 'CSV$');
if (d < 0);
msg = IFS_error();
dsply msg;
return;
endif;
dsply ' ** ending in CSV **';
dow (IFS_readdir(d: file) > 0);
msg = file;
dsply msg;
enddo;
dsply ' ** not ending in CSV **';
IFS_rewinddir(d: *ON);
dow (IFS_readdir(d: file) > 0);
msg = file;
dsply msg;
enddo;
IFS_closedir(d);
return;
/end-free
To build the utility, I provide a CL program called BUILD that's also included in the code download. There's also a readme.txt file that contains further instructions about how to build the utility.
The CL commands in this utility are based on the ones that I demonstrated in the May 19, 2005, issue of this newsletter. You can read that article at the following link: http://www.iseriesnetwork.com/article.cfm?id=50930
The RPG code in this utility is based on code demonstrated in the May 12, 2005, issue of this newsletter. You can read that article at the following link: http://www.iseriesnetwork.com/article.cfm?id=50900
I'm frequently asked how to translate data from EBCDIC to ASCII, or EBCDIC to Unicode, or between the character sets used by different cultures. In most cases, the best solution to these translations is the iconv() API.
The key to using iconv() on the iSeries is knowing which Coded Character Set Identifiers (CCSIDs) you need to translate between. A CCSID is a number that identifies a character set that has been encoded a particular way. For example, to identify the character set used in the U.S. when encoded in single-byte EBCDIC, we can refer to CCSID 37. The number 37 is just an identifying number that IBM assigns to that particular character set when it's encoded as EBCDIC so that when the time comes to translate to or from U.S. EBCDIC, all we need to specify is 37 for the CCSID parameter.
To get started with iconv(), you have to open a "conversion descriptor." That's a technical way of saying that the system needs to find the right translation table and reserve some memory for work variables that it uses internally. To do that, you pass the CCSIDs to the QtqIconvOpen() API. It takes care of finding the right table, loading it into memory for quick access, and reserving memory for the internal work variables. Here's an example of opening a conversion descriptor:
/copy iconv_h
D from ds likeds(QtqCode_T)
D inz(*LIKEDS)
D to ds likeds(QtqCode_T)
D inz(*LIKEDS)
D table ds likeds(iconv_t)
/free
from.CCSID = 37;
to.CCSID = 819;
table = QtqIconvOpen(to: from);
if (table.return_value = -1);
errMsg = 'Unable to load translation table';
// FIXME: show message to user.
*inlr = *on;
return;
endif;
To make calling iconv() as simple as possible, I put all the definitions that I need in the ICONV_H source member, and I use the /COPY directive to bring those definitions into each program that uses iconv(). In the preceding code, "from" and "to" are copies of a data structure stored in the ICONV_H member. The only field in that data structure that I need to change is the CCSID field, so that I can tell the API which CCSIDs to convert between. I pass the data structures containing these CCSIDs to QtqIconvOpen(), and it finds the table, reserves memory for work variables, and returns a conversion descriptor. The descriptor is actually a data structure also defined in ICONV_H. It contains a subfield called return_value, and I can check that subfield to verify that QtqIconvOpen() completed successfully.
Now that I have the translation table loaded, I can pass it to the iconv() API to translate some data. The prototype for the iconv() API is defined in ICONV_H as well. This is what the prototype looks like:
d iconv PR 10I 0 extproc('iconv')
d cd like(iconv_t) value
d inbuf *
d inbytesleft 10U 0
d outbuf *
d outbytesleft 10U 0
The first parameter to iconv() is the conversion descriptor. The remaining parameters are a pointer to the next character to convert, the number of characters left to convert, a pointer to the memory where the translated character should be stored, and the amount of memory that remains for converted characters.
Iconv() reads your input data one character at a time and converts it to an output character. After that character is translated, it changes the pointers to point to the next character to be translated and decreases the bytes left for the input and output buffers. It continues doing this in a loop (converting each character and updating the parameters) until it runs out of characters to translate, runs out of space in the output buffer, or finds a character that it can't translate.
Because the pointers and space left fields are updated as iconv() runs, if an error occurs, you can call iconv() back, and it picks up where it left off.
Here's an example of translating a string from EBCDIC to ASCII using the conversion descriptor from the preceding code snippet:
D p_input s *
D inleft s 10U 0
D p_output s *
D outleft s 10U 0
D input_data1 s 50A
D output_data1 s 200A
.
.
input_data1 = 'Hello, my name is Scott';
output_data1 = *blanks;
p_input = %addr(input_data1);
inleft = %len(input_data1);
p_output = %addr(output_data1);
outleft = %size(output_data1);
iconv( table
: p_input
: inleft
: p_output
: outleft );
In the preceding code snippet, I start by pointing the input and output pointers to variables in my program. I set up the "bytes left" fields to be the length of the data to translate and the amount of memory to receive the results. I then call iconv() to perform the translation.
Translating data stored in a VARYING string is a little more complicated because the API doesn't know anything about VARYING. You see, VARYING is an RPG concept in which a character string is prefixed by a two-byte field containing the length of the string. Because the API is unfamiliar with VARYING, we can skip those two bytes (by adding two to the pointer), and it translates the character data without even knowing that the string is VARYING. Here's an example of using iconv() with a VARYING string:
D input_data2 s 50A varying
D output_data2 s 200A varying
.
.
input_data2 = 'Goodbye, it was nice meeting you!';
%len(output_data2) = %size(output_data2) - 2;
p_input = %addr(input_data2) + 2;
inleft = %len(input_data2);
p_output = %addr(output_data2) + 2;
outleft = %len(output_data2);
iconv( table
: p_input
: inleft
: p_output
: outleft );
%len(output_data2) = %len(output_data2) - outleft;
Because a pointer points to a particular byte in memory, adding two to that pointer points two bytes later in memory. Therefore, it effectively skips over the length that's prefixed to the VARYING fields.
Because the output variable is also VARYING, I set its length to the maximum length that can be stored in the field before the conversion. After the conversion is complete, I use the "bytets left" field to determine how much data was actually placed in the output field, and I adjust the length accordingly.
You can use the same conversion descriptor to translate as many strings as you like. When you're done converting data with iconv(), you should call the iconv_close() API. This lets the system free up the memory for its internal work variables so that the memory is available for other tasks.
Here's an example of calling iconv_close():
iconv_close(table);
Instead of specifying a CCSID when you call QtqIconvOpen(), you can specify a special value of zero. If you specify zero, it tells iconv() that you'd like to use the default CCSID for the current job. For example, instead of hard-coding 37 for the EBCDIC CCSID of my data in the previous examples, I could've specified zero as follows:
/copy iconv_h
D from ds likeds(QtqCode_T)
D inz(*LIKEDS)
D to ds likeds(QtqCode_T)
D inz(*LIKEDS)
D table ds likeds(iconv_t)
/free
from.CCSID = 0;
to.CCSID = 819;
table = QtqIconvOpen(to: from);
if (table.return_value = -1);
errMsg = 'Unable to load translation table';
// FIXME: show message to user.
*inlr = *on;
return;
endif;
Using the job's default CCSID is especially useful when the data that you translate is data that the user keyed in. It saves you the effort of trying to figure out what CCSID the user's data will be. Assuming that the job's CCSID was set up properly, it'll be the correct one for the data that the user types.
You'll find IBM's documentation for iconv() and related APIs in the Information Center. These APIs are part of the Code Conversion subcategory of the National Language Support APIs category. Here's a link to that section of the Information Center: http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/nls3.htm
* SqlSTATE Codes D StateSucces C Const('00000') D StateWarning C Const('00001') D StateNoData C Const('00002') D StateRowNotFnd C Const('00100') D StateNoRow C Const('02000') D StateDupKey C Const('23505')
// A error occured in the write/update/delete operation ? If SqlStt <> StateSucces and SqlStt <> StateNoRow; Exsr *Pssr; Endif;
Endsr; // CheckSqlState
/End-Free
// ============================================================ // Procedure : Update creation order number in OR file. // ============================================================ P UpdateOrOrdn B
* Procedure Interface D UpdateOrOrdn Pi
C/EXEC SQL C+ Update OR C+ Set OrOrdn = OrOrdn + 1000000000, C+ OrLsad = :P_DatPf, C+ OrLsai = :#Pgm C+ Where OrOrdn > 0 and OrOrdn < 1000000000 C/END-EXEC
P UpdateOrOrdn E
// =========================================================== // Procedure : Update creation order number in GC file. // =========================================================== P UpdateGcCorn B
* Procedure Interface D UpdateGcCorn Pi
C/EXEC SQL C+ Update GC C+ Set GcCorn = GcCorn + 1000000000, C+ GcLsad = :P_DatPf, C+ GcLsai = :#Pgm C+ Where GcCorn > 0 and GcCorn < 1000000000 C/END-EXEC
