Retrieving Data

One of CL's specialties is its ability to retrieve data from system objects, such as user profiles, data areas, and system values.

Data Areas

Data areas are objects of type *DTAARA that you can use to store small pieces of information, such as report headings or the name of your company.

You can create, change, delete, and display data areas. You use the obvious commands CRTDTAARA, CHGDTAARA, DLTDTAARA, and DSPDTAARA. These commands can be placed easily in CL programs.

Whenever you manipulate a data area, you must reference the beginning position and the length of the data. For example, you may want to change the contents of the data area. Use the CHGDTAARA command and specify what position to begin changing, and how many characters:

      CHGDTAARA DTAARA(ABC (25 3)) VALUE('***') 

This command changes positions 25, 26, and 27 of data area ABC to asterisks.

CL allows you to retrieve their contents and place them in a CL variable. It is akin to reading a file. To retrieve the contents of a data area into a CL variable, you use the Retrieve Data Area (RTVDTAARA) command. The name of the CL variable goes into the RTNVAR parameter, as follows:

      RTVDTAARA DTAARA(ABC (16 5)) RTNVAR(&VALUE) 

In this example, variable &VALUE receives the value contained in positions 16 to 20 of data area ABC.

System Values

System values are very important entities used to configure the system. You can find more information on system values in Chapter 11. CL programs can contain the Display, Change, and Work with System Values (DSPSYSVAL, CHGSYSVAL, and WRKSYSVAL) commands used to manipulate them. Thus, a CL program is capable of changing the configuration of the system if the person who runs the program has sufficient authority.

CL programs can also retrieve the current value of system values using the Retrieve System Value (RTVSYSVAL) command. Depending on which system value you are retrieving, the value must be given to a character or decimal variable. The value must also be a particular length, which also depends on the system value.

For example, your CL program can retrieve the value of QTIME, the system value that holds the system time, as follows:

      RTVSYSVAL SYSVAL(QTIME) RTNVAR(&SYSTIM) 

This statement assumes that &SYSTIM is a six-character string variable. When RTVSYSVAL executes, &SYSTIM will contain the time of day at the moment RTVSYSVAL was executed, in the format HHMMSS.

Other Information

You can retrieve a lot more information into CL variables using other Retrieve (RTV XXX) commands. Among them, two very important ones are:

• RTVJOBA. The Retrieve Job Attributes command lets you find out about the settings of your own job, the one in which the CL program is running. For example, you can retrieve the name of the current output queue with the OUTQ and OUTQLIB parameters, or the name of the display station from which you are running the command (if running interactively) with the job parameter. The TYPE parameter returns ‘0’ if the job is running in batch or ‘1’ otherwise.

• RTVUSRPRF. The Retrieve User Profile command allows you to retrieve important information about any user profile. If you do not specify which user profile, your own is assumed.

If you wish, you can find other RTV XXX commands available in i5/OS by executing the following command:

      SLTCMD CMD(QSYS/RTV*)