System i

Programming Control language

Version 5 Release 4

System i

Programming Control language

Version 5 Release 4

Note Before using this information and the product it supports, read the information in Notices, on page 571.

Sixth Edition (February 2006) This edition applies to version 5, release 4, modification 0 of IBM i5/OS (product number 5722-SS1) and to all subsequent releases and modifications until otherwise indicated in new editions. This version does not run on all reduced instruction set computer (RISC) models nor does it run on CISC models. Copyright International Business Machines Corporation 1998, 2006. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents
Control language . . . . . . . . . . . 1
Overview: Control language . . . . . . . . . 1 Whats new for V5R4 . . . . . . . . . . . 1 Printable PDFs . . . . . . . . . . . . . . 2 CL concepts . . . . . . . . . . . . . . 4 System operation control . . . . . . . . . 4 Control language . . . . . . . . . . . 4 Menus . . . . . . . . . . . . . . 4 Messages . . . . . . . . . . . . . 4 Message descriptions . . . . . . . . 5 Message queues . . . . . . . . . . 5 CL commands . . . . . . . . . . . . . 6 CL command names . . . . . . . . . . 6 Abbreviations of CL commands and keywords . . . . . . . . . . . . 7 CL command parts . . . . . . . . . . 39 CL command syntax . . . . . . . . 39 CL command label . . . . . . . . . 40 CL command parameters . . . . . . . 41 CL command delimiters . . . . . . . 41 CL command continuation . . . . . . 43 CL command comments . . . . . . . 44 CL command definition parts . . . . . . 44 CL command coding rules . . . . . . . 45 CL command information and documentation 47 CL command documentation format . . . 47 CL command help . . . . . . . . . 50 Printing CL command descriptions on the system . . . . . . . . . . . . . 51 CL command prompters . . . . . . . 51 CL commands that operate on i5/OS objects 51 CL commands that operate on multiple objects 52 CL programs and procedures . . . . . . . 53 CL procedure . . . . . . . . . . . . 54 CL module . . . . . . . . . . . . 54 CL program . . . . . . . . . . . . 54 Service program . . . . . . . . . . . 55 CL parameters . . . . . . . . . . . . 55 Parameter values . . . . . . . . . . 55 Constant value . . . . . . . . . . 55 Variable name . . . . . . . . . . 60 Expressions . . . . . . . . . . . 61 List of values . . . . . . . . . . . 62 Parameters in keyword and positional form 63 Required, optional, and key parameters . . . 64 Commonly used parameters . . . . . . . 65 AUT parameter . . . . . . . . . . 65 CLS parameter . . . . . . . . . . 66 COUNTRY parameter . . . . . . . . 67 FILETYPE parameter . . . . . . . . 74 FRCRATIO parameter . . . . . . . . 75 IGCFEAT parameter . . . . . . . . 76 JOB parameter . . . . . . . . . . 76 LABEL parameter . . . . . . . . . 78 LICOPT parameter . . . . . . . . . 79 MAXACT parameter . . . . . . . . 82
Copyright IBM Corp. 1998, 2006

OBJ parameter . . . . . . . . OBJTYPE parameter . . . . . . OUTPUT parameter . . . . . . PRTTXT parameter . . . . . . . REPLACE parameter . . . . . . JOBPTY, OUTPTY, and PTYLMT scheduling priority parameters . . . SEV parameter . . . . . . . . SPLNBR parameter . . . . . . . TEXT parameter . . . . . . . . VOL parameter . . . . . . . . WAITFILE parameter . . . . . . Parameter values used for testing and debugging . . . . . . . . . . . Program-variable description . . . Basing-pointer description . . . . Subscript description . . . . . . Qualified-name description . . . . Control language elements . . . . . . CL character sets and values . . . . . Character sets . . . . . . . . Special character use . . . . . . Symbolic operators . . . . . . . Predefined values . . . . . . . Expressions in CL commands . . . . Arithmetic expressions . . . . . Character string expressions . . . Relational expressions . . . . . Logical expressions . . . . . . Operators in expressions . . . . Priority of operators when evaluating expressions . . . . . . . . . Built-in functions for CL . . . . . . Naming within commands . . . . . Folder and document names . . . i5/OS objects . . . . . . . . . . Library objects . . . . . . . . . External object types . . . . . . . Simple and qualified object names . . Generic object names . . . . . . . Object naming rules . . . . . . . Communication names (*CNAME) . Generic names (*GENERIC) . . . Names (*NAME) . . . . . . . Path names (*PNAME) . . . . . Simple names (*SNAME) . . . . Additional rules for unique names . Database files and device files used by CL commands . . . . . . . . . . . CL programming . . . . . . . . . . Process for creating a CL source program or procedure . . . . . . . . . . . Interactive entry . . . . . . . . Batch entry . . . . . . . . . . Parts of a CL procedure . . . . . . Example: Simple CL procedure . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . .

83 83 85 85 86 88 89 90 91 91 93

. 94 . 94 . 95 . 95 . 96 . 97 . 97 . 97 . 98 . 99 . 100 . 100 . 101 . 101 . 103 . 104 . 104 . . . . . . . . . . . . . . . . 106 106 107 108 109 111 112 116 116 118 120 120 120 121 123 124 124 158 159 160 160 161 162

. . . . CL . . . . . . . . . .

iii

| |

| | | | | | |

Commands used in CL procedures . . . . . Common commands used in CL procedures Operations performed by CL procedures . . . Variables in CL commands . . . . . . . . Declaring variables to a CL procedure . . . Uses for based variables . . . . . . . . Uses for defined variables . . . . . . . Variables to use for specifying a list or qualified name . . . . . . . . . . . Cases of characters in variables . . . . . Variables that replace reserved or numeric parameter values . . . . . . . . . . Changing the value of a variable . . . . . Trailing blanks on command parameters . . Writing comments in CL procedures . . . . Controlling processing within a CL program or CL procedure . . . . . . . . . . . . GOTO command and command labels in a CL program or procedure . . . . . . . IF command in a CL program or procedure ELSE command in a CL program or procedure . . . . . . . . . . . . Embedded IF commands in a CL program or procedure . . . . . . . . . . . . DO command and DO groups in a CL program or procedure . . . . . . . . DOUNTIL command in a CL program or procedure . . . . . . . . . . . . DOWHILE command in a CL program or procedure . . . . . . . . . . . . DOFOR command in a CL program or procedure . . . . . . . . . . . . ITERATE command in a CL program or procedure . . . . . . . . . . . . LEAVE command in a CL program or procedure . . . . . . . . . . . . CALLSUBR command in a CL program or procedure . . . . . . . . . . . . SELECT command and SELECT groups in a CL program or procedure . . . . . . . SUBR command and subroutines in a CL program or procedure . . . . . . . . *AND, *OR, and *NOT operators . . . . . %ADDRESS built-in function in a CL program or procedure . . . . . . . . %BINARY built-in function . . . . . . . %OFFSET built-in function . . . . . . . %SUBSTRING built-in function . . . . . %SWITCH built-in function . . . . . . %SWITCH with the IF command . . . . %SWITCH with the Change Variable command . . . . . . . . . . . Monitor Message command . . . . . . Retrieving values that can be used as variables Retrieving system values . . . . . . . Example: Retrieving QTIME system value Retrieving the QDATE system value into a CL variable . . . . . . . . . . . Retrieving configuration source . . . . . Retrieving configuration status . . . . . Retrieving network attributes . . . . . .

164 164 167 171 172 174 174 175 176 176 177 179 180 181 182 183 184 187 188 190 191 192 193 193 194 195 196 197 201 202 204 205 207 208 209 209 211 211 211 212 214 214 214

Example: Using the Retrieve Network Attributes command . . . . . . . . Retrieving job attributes . . . . . . . . Example: Using the Retrieve Job Attributes command . . . . . . . . Retrieving user profile attributes . . . . . Example: Using the Retrieve User Profile command . . . . . . . . . . . Retrieving member description information Example: Using the Retrieve Member Description command . . . . . . . Compiling CL procedures . . . . . . . . Logging CL procedure commands . . . . CL module compiler listings . . . . . . Common compilation errors . . . . . . Obtaining a CL procedure dump . . . . . Displaying module attributes . . . . . . Displaying program attributes . . . . . . Return code summary . . . . . . . . Compiling source programs for a previous release . . . . . . . . . . . . . . . Previous-release (*PRV) libraries . . . . . Installing CL compiler support for a previous release . . . . . . . . . . . . . . Controlling flow and communicating between programs and procedures . . . . . . . . Passing control to another program or procedure . . . . . . . . . . . . Using the Call Program command to pass control . . . . . . . . . . . . Using the Call Bound Procedure command to pass control . . . . . . Using the Return command to pass control . . . . . . . . . . . . Passing parameters . . . . . . . . . Using the Call Program command to pass control to a called program . . . . . . Common errors when calling programs and procedures . . . . . . . . . . Communicating between programs and procedures . . . . . . . . . . . . . Using data queues . . . . . . . . . . Remote data queues . . . . . . . . Comparisons with using database files as queues . . . . . . . . . . . . Similarities to message queues. . . . . Prerequisites for using data queues . . . Managing the storage used by a data queue . . . . . . . . . . . . . Allocating data queues . . . . . . . Examples: Using a data queue . . . . . Creating data queues associated with an output queue . . . . . . . . . . Using data areas . . . . . . . . . . Local data area . . . . . . . . . . Group data area . . . . . . . . . Program Initialization Parameter data area Remote data areas . . . . . . . . . Creating a data area . . . . . . . . Data area locking and allocation . . . . Displaying a data area . . . . . . .

215 215 215 216 216 217 217 218 218 220 222 223 224 224 225 226 226 227 227 227 227 229 230 231 234 236 240 241 243 244 245 245 245 246 246 251 251 252 253 253 254 254 255 255

iv

System i: Programming Control language

Changing a data area . . . . . . . . Retrieving a data area . . . . . . . Examples: Retrieving a data area . . . . Example: Changing and retrieving a data area . . . . . . . . . . . . . Defining and documenting commands . . . . Defining commands . . . . . . . . . Command definition statements . . . . Command definition process . . . . . Defining a command . . . . . . . . Data type and parameter restrictions . . Defining lists for parameters . . . . . Specifying prompt control . . . . . . Key parameters and prompt override programs . . . . . . . . . . . . Creating commands . . . . . . . . Displaying a command definition . . . Effect of changing the command definition of a command in a procedure or program . Command processing program . . . . Validity checking program . . . . . . Examples: Defining and creating commands . . . . . . . . . . . Documenting command . . . . . . . . Commands and command help . . . . Writing command help . . . . . . . Generating HTML source for command documentation . . . . . . . . . . Proxy commands . . . . . . . . . . Command-related APIs . . . . . . . . . QCAPCMD program . . . . . . . . . QCMDEXC program . . . . . . . . . QCMDEXC program with DBCS data . . QCMDCHK program . . . . . . . . . Prompting for user input at run time . . . . Using the i5/OS prompter within a CL procedure or program . . . . . . . . Using selective prompting for CL commands Using QCMDEXC with prompting in CL procedures and programs . . . . . . . Entering program source . . . . . . . . Using the Start Programmer Menu command Using the EXITPGM parameter of the Start Programmer Menu command . . . Command analyzer exit points . . . . . . Designing application programs for DBCS data Designing DBCS application programs . . . Converting alphanumeric programs to process DBCS data . . . . . . . . . Using DBCS data in a CL program . . . . Loading and running an application from tape or optical media . . . . . . . . . . . Example: QINSTAPP program . . . . . . Transferring control to improve performance Example: Using the Transfer Control command . . . . . . . . . . . . Passing parameters using the Transfer Control command . . . . . . . . . . Examples: CL programs and procedures . . . Example: Initial program for setup (programmer) . . . . . . . . . . .

256 256 256 257 258 258 258 261 265 271 278 294 297 304 308 309 313 316 318 324 324 326 327 328 329 329 329 332 332 334 334 336 339 339 339 340 340 341 341 341 341 342 342 343 343 344 345 346

Example: Saving specific objects in an application (system operator) . . . . . . Example: Recovery from abnormal end (system operator) . . . . . . . . . . Example: Timing out while waiting for input from a device display . . . . . . . . Example: Performing date arithmetic . . . Debugging CL programs and procedures . . . . Debugging ILE programs . . . . . . . . Debug commands . . . . . . . . . . Preparing a program object for a debug session . . . . . . . . . . . . . Using a root source view to debug ILE programs . . . . . . . . . . . . Using a listing view to debug ILE programs . . . . . . . . . . . . Using a statement view to debug ILE programs . . . . . . . . . . . . Starting the ILE source debugger . . . . . Adding program objects to a debug session Removing program objects from a debug session . . . . . . . . . . . . . Viewing the program source . . . . . . Changing a module object . . . . . . Changing the module object view . . . Setting and removing breakpoints . . . . Setting and removing unconditional breakpoints . . . . . . . . . . . Setting and removing conditional breakpoints . . . . . . . . . . . Using the Work with Breakpoints display Using the BREAK and CLEAR debug commands to set and remove conditional breakpoints . . . . . . . . . . . National Language Sort Sequence . . . Examples: Conditional breakpoint . . . Removing all breakpoints . . . . . . Using instruction stepping . . . . . . . F10 (Step) to step over program objects or F22 (Step into) to step into program objects . . . . . . . . . . . . . Using the STEP debug command to step through a program object . . . . . . Displaying variables . . . . . . . . . Example: Displaying logical variable . . Examples: Displaying character variable Example: Displaying decimal variable . . Example: Displaying variables as hexadecimal values . . . . . . . . Changing the value of variables . . . . . Example: Changing logical variable . . . Examples: Changing character variable Examples: Changing decimal variable . . Displaying variable attributes . . . . . . Equating a name with a variable, an expression, or a command . . . . . . . Source debug and i5/OS globalization . . . Working with *SOURCE view . . . . . Operations that temporarily remove steps Debugging original program model programs Starting debug mode . . . . . . . . .
Contents

346 346 346 348 348 349 350 351 351 352 352 353 353 355 356 356 357 358 358 359 360

361 361 362 363 363

363 364 364 365 366 366 366 367 367 368 368 368 369 370 370 370 370 371

Adding programs to debug mode . . . Preventing updates to database files in production libraries . . . . . . . . Displaying the call stack . . . . . . . . Program activations . . . . . . . . Handling unmonitored messages . . . . . Breakpoints . . . . . . . . . . . . Adding breakpoints to programs . . . . Adding conditional breakpoints . . . . Removing breakpoints from programs . . Traces . . . . . . . . . . . . . . Adding traces to programs . . . . . . Using instruction stepping . . . . . . Using breakpoints within traces . . . . Removing trace information from the system . . . . . . . . . . . . Removing traces from programs . . . . Displaying testing information . . . . . Displaying the values of variables . . . . Changing the values of variables . . . . . Reasons for using a job to debug another job Debugging batch jobs that are submitted to a job queue . . . . . . . . . . Debugging batch jobs that are not started from job queues . . . . . . . . . Debugging a job that is running . . . . Debugging another interactive job . . . Considerations when debugging one job from another job . . . . . . . . . Debugging at the machine interface level . . Security considerations . . . . . . . . Operations that temporarily remove breakpoints . . . . . . . . . . . . Objects and libraries . . . . . . . . . . . Objects . . . . . . . . . . . . . . Object types and common attributes . . . . Functions performed on objects . . . . . Functions the system performs automatically . . . . . . . . . . Functions you can perform using commands . . . . . . . . . . . Libraries . . . . . . . . . . . . . . Library lists . . . . . . . . . . . . Functions of using a library list . . . . A jobs library list . . . . . . . . . Changing the library list . . . . . . . Considerations for using a library list . . Displaying a library list . . . . . . . Using library lists to search for objects . . Using libraries . . . . . . . . . . . . Creating a library . . . . . . . . . . Authority for libraries specification . . . . Object authority . . . . . . . . . Data authority . . . . . . . . . . Combined authority . . . . . . . . Security considerations for objects . . . . The Display Audit Journal Entries command to generate security journal audit reports . . . . . . . . . . Setting default public authority . . . . . Setting default auditing attribute . . . . .

372 372 373 373 374 375 375 378 379 380 380 382 383 383 383 383 384 385 386 386 387 387 388 388 389 389 389 390 390 390 391 391 391 392 392 394 398 399 401 401 401 403 403 404 404 404 405 405

406 406 407

Placing objects in libraries . . . . . . . Deleting and clearing libraries . . . . . . Displaying library names and contents . . . Displaying and retrieving library descriptions Changing national language versions . . . . Describing objects . . . . . . . . . . . Displaying object descriptions . . . . . . . Retrieving object descriptions . . . . . . . Example: Using the Retrieve Object Description command . . . . . . . . Creation information for objects . . . . . . Detecting unused objects on the system . . . Moving objects from one library to another . . Creating duplicate objects . . . . . . . . Renaming objects . . . . . . . . . . . Object compression or decompression . . . . Restrictions for compression of objects . . . Temporarily decompressed objects . . . . Automatic decompression of objects . . . . Deleting objects . . . . . . . . . . . Allocating resources . . . . . . . . . . Lock states for objects . . . . . . . . Displaying the lock states for objects . . . Accessing objects in CL programs . . . . . Accessing command definitions, files, and procedures . . . . . . . . . . . . Accessing command definitions . . . . Accessing files . . . . . . . . . . Accessing procedures . . . . . . . . Checking for the existence of an object . . . Working with files in CL procedures . . . . Data manipulation commands . . . . . . Files in a CL procedure . . . . . . . . Opening and closing files in a CL procedure Declaring a file . . . . . . . . . . . Sending and receiving data with a display file . . . . . . . . . . . . . . . Example: Writing a CL program to control a menu . . . . . . . . . . . . . . The Override with Display File command to override display files in a CL procedure or program . . . . . . . . . . . . . Working with multiple device display files The Receive File command to receive data from a database file . . . . . . . . . The Override with Database File command to override database files in a CL procedure or program . . . . . . . . . . . . Output files from display commands . . . Messages . . . . . . . . . . . . . . . Defining message descriptions . . . . . . . Creating a message file . . . . . . . . Message files in independent ASPs . . . Determining the size of a message file . . Adding messages to a file . . . . . . . Assigning a message identifier . . . . Defining messages and message help . . Defining substitution variables . . . . Assigning a severity code . . . . . . Specifying validity checking for replies

407 408 409 410 410 411 411 415 417 417 418 422 425 426 428 428 429 429 430 431 432 434 434 435 436 436 437 437 438 440 441 441 442 443 445

446 447 450

450 451 452 453 455 455 455 456 457 458 458 460 461

vi

System i: Programming Control language

Example: Sending an immediate message and handling a reply . . . . . . . . Defining default values for replies . . . Specifying default message handling for escape messages . . . . . . . . . Example: Describing a message . . . . Defining double-byte messages . . . . Viewing messages . . . . . . . . . . Message file searching . . . . . . . . System message file searches . . . . . Overriding message files . . . . . . Message queues . . . . . . . . . . . Types of message queues . . . . . . . Creating or changing a message queue . . . Message queues in independent ASPs . . Message queues in break mode . . . . Placing a message queue in break mode automatically . . . . . . . . . . Job message queues . . . . . . . . . External message queue . . . . . . . Call message queue . . . . . . . . Commands used to send messages to a system user . . . . . . . . . . . . . . . Commands used to send messages from a CL program . . . . . . . . . . . . . . Inquiry and informational messages . . . . Completion and diagnostic messages . . . Status messages . . . . . . . . . . Escape and notify messages . . . . . . Examples: Sending messages . . . . . . Identifying a call stack entry . . . . . . Using the Send Program Message command as the base . . . . . . . . Identifying the base entry by name . . . Using the program boundary as a base Using the most recently called procedure as a base . . . . . . . . . . . . Using a control boundary as a base . . . Considerations for service programs . . . Receiving messages into a CL procedure or program . . . . . . . . . . . . . . Receiving request messages . . . . . . Writing request-processor procedures and programs . . . . . . . . . . . . . Determining if a request processor exists . . Retrieving message descriptions from a message file . . . . . . . . . . . . . . . . Removing messages from a message queue . . Monitoring for messages in a CL program or procedure . . . . . . . . . . . . .

462 464 464 466 466 467 467 467 467 471 471 473 474 475 475 476 476 477 479 480 482 482 483 483 484 487 488 490 493 497 498 500 501 503 505 506 508 509 510

| | | | |

Watching for messages . . . . . . . . CL handling for unmonitored messages . . Monitoring for notify messages . . . . . Monitoring for status messages . . . . . Preventing the display of status messages Receiving a message from a program or procedure that has ended . . . . . . . . Break-handling programs . . . . . . . . Ways of handling replies to inquiry messages Using a sender copy message to obtain a reply . . . . . . . . . . . . . . Finding the job that sent the reply . . . . Using the system reply list . . . . . . . Using the reply handling exit program . . . Message subfiles in a CL program or procedure Log messages . . . . . . . . . . . . Job log . . . . . . . . . . . . . Writing a job log to a file . . . . . . Controlling information written in a job log . . . . . . . . . . . . . . Job log message filtering . . . . . . Example: Controlling information written in a job log . . . . . . . . . . . Job log sender or receiver information . . Displaying a job log . . . . . . . . Preventing the production of job logs . . Job log considerations . . . . . . . Interactive job log considerations . . . . Batch job log considerations . . . . . Message filtering through the Control Job Log Output API . . . . . . . . . Job log output files . . . . . . . . QHST history log . . . . . . . . . . Format of the history log . . . . . . QHST file processing . . . . . . . . QHST job start and completion messages QHST files deletion . . . . . . . . QSYSMSG message queue . . . . . . . . Messages sent to QSYSMSG message queue Example: Receiving messages from QSYSMSG . . . . . . . . . . . .

513 513 515 516 516 517 520 522 522 523 523 526 527 527 527 527 528 529 529 533 534 535 535 536 537 538 538 546 548 549 550 551 551 552 568

Appendix. Notices . . . . . . . . . 571

Programming Interface Information . Trademarks . . . . . . . . . Terms and conditions . . . . . . . . . . . . . . . . . . . 572 . 572 . 573

Contents

vii

viii

System i: Programming Control language

Control language
Control language (CL) allows system programmers and system administrators to write programs using i5/OS commands and other IBM-supplied commands. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569.

Overview: Control language

The control language topic collection contains information about all control language (CL) commands that are part of the i5/OS operating system. It also includes many CL commands for licensed programs that run on the i5/OS operating system. Before using CL commands, you should be familiar with the CL programming concepts discussed in the Control language topic collection.

Who should use commands

CL commands are typically used by programmers, data processing managers, and system administrators. Through i5/OS command menus, powerful command prompter tools, and online command help, nontechnical users can also use CL commands. To use commands, you should have a general understanding of i5/OS operating system. If you want to combine several CL commands together to create a CL program, some background in programming is helpful.

How this information is organized

In the CL command finder, you can search for commands by product, by command name, by descriptive name, or by part of the name. You also can search for new commands and changed commands. You can also view an alphabetical list of all of the command documentation. Related reference Printable PDFs on page 2 Use this to view and print groups of CL commands or concepts.

Whats new for V5R4

This topic highlights changes to Control language (CL) for IBM i5/OS V5R4. New object types The following object types are new in the i5/OS licensed program for Version 5 Release 4 Modification 0 (V5R4M0): v *NWSCFG -- Network Server Configuration object CL concept information This release the CL Programming manual has been discontinued, and the information has been moved and integrated with the CL concept information in the CL topic. See Control Language concepts and reference to print this information. The CL concept information includes new CL support for the following: v subroutines
Copyright IBM Corp. 1998, 2006

v v v v

pointer variables based variables defined variables %ADDRESS and %OFFSET built-in functions

New and changed commands You can display a list of all new commands or all changed commands using the CL command finder. However, the command information content is not marked to indicate what is new or changed.

How to see whats new or changed

To help you see where technical changes have been made, this information uses: v The image to mark where new or changed information begins. v The image to mark where new or changed information ends.

To find other information about whats new or changed this release, see the Memo to users.

Printable PDFs
Use this to view and print groups of CL commands or concepts. The following links provide the PDF versions of the CL concepts and reference information, as well as the CL command descriptions. (For information about printing command information from your system, see Printing CL command descriptions on the system on page 51). To view or download a PDF, select one of the following links.
CL PDF Control language i5/OS commands starting with ADDACC (Add Access Code) i5/OS commands starting with AREXEC (Run Remote Command) i5/OS commands starting with CHGDSTL (Change Distribution List) i5/OS commands starting with CHGPRXCMD (Change Proxy Command) PDF download size (pages) 8340 KB (558 pages) 6621 KB (664 pages) 7358 KB (738 pages) 9103 KB (894 pages) 6485 KB (654 pages)

i5/OS commands starting with CPYIGCTBL (Copy DBCS 10 876 KB (992 pages) Font Table) i5/OS commands starting with CRTMSGF (Create Message File) i5/OS commands starting with DLTF (Delete File) i5/OS commands starting with DSPAPPNINF (Display APPN Information) i5/OS commands starting with DSPNWSD (Display Network Server Description) i5/OS commands starting with ENDJOB (End Job) i5/OS commands starting with MRGTCPHT (Merge TCP/IP Host Table) 6374 KB (620 pages) 2712 KB (338 pages) 3409 KB (378 pages) 3463 KB (378 pages) 4421 KB (474 pages) 6376 KB (642 pages)

System i: Programming Control language

CL PDF i5/OS commands starting with RMVDEVDMNE (Remove Device Domain Entry) i5/OS commands starting with RSTSYSINF (Restore System Information) i5/OS commands starting with SNDRPY (Send Reply) i5/OS commands starting with VFYCMN (Verify Communications) i5/OS commands starting with WRKNTWAUTE (Work with NetWare Authentication Entries) Advanced Job Scheduler for iSeries commands AFP Utilities for iSeries commands Backup Recovery and Media Services for iSeries commands Business Graphics Utility for AS/400 commands CICS Transaction Server for iSeries commands Communications Utilities for iSeries commands Content Manager OnDemand for iSeries commands Cryptographic Support for AS/400 commands DB2 DataPropagator for iSeries, V8.1 commands DB2 Query Manager and SQL Development Kit for iSeries commands Developer Kit for Java commands HTTP Server for iSeries commands Infoprint Server for iSeries commands IBM eServer iSeries Access for Web commands Managed System Services for iSeries commands Performance Tools for iSeries commands Query for iSeries commands System Manager for iSeries commands TCP/IP Connectivity Utilities for iSeries commands WebSphere Development Studio commands

PDF download size (pages) 3919 KB (404 pages) 9176 KB (866 pages) 5194 KB (532 pages) 2769 KB (320 pages) 2190 KB (248 pages) 1618 KB (176 pages) 410 KB (50 pages) 4701 KB (490 pages) 275 KB (34 pages) 3024 KB (328 pages) 1504 KB (176 pages) 1447 KB (166 pages) 391 KB (50 pages) 866 KB (110 pages) 1981 KB (192 pages) 262 KB (28 pages) 421 KB (50 pages) 379 KB (48 pages) 208 KB (38 pages) 937 KB (112 pages) 2214 KB (256 pages) 92 KB (14 pages) 3766 KB (424 pages) 1569 KB (182 pages) 3309 KB (360 pages)

Saving PDF files

To 1. | 2. 3. 4. save a PDF on your workstation for viewing or printing: Right-click the PDF in your browser (right-click the link above). Click the option that saves the PDF locally. Navigate to the directory in which you want to save the PDF. Click Save.

Downloading Adobe Reader

| You need Adobe Reader installed on your system to view or print these PDFs. You can download a free | copy from the Adobe Web site ([Link]/products/acrobat/[Link]) .
Control language

Related concepts Overview: Control language on page 1 The control language topic collection contains information about all control language (CL) commands that are part of the i5/OS operating system. It also includes many CL commands for licensed programs that run on the i5/OS operating system. Printing CL command descriptions on the system on page 51 To print the parameter and value descriptions for a CL command, follow these instructions.

CL concepts
The control language (CL) is the set of all commands with which a user requests system functions. This information describes the basic concepts of CL that you need to understand before you use the commands.

System operation control

The control language (CL), menu options, and system messages control the operation of the system.

Control language
Control language (CL) is the primary interface to the operating system. CL can be used at the same time by users at different workstations, in batch and interactive jobs and in CL programs and procedures. A single control language statement is called a command. Commands can be entered in the following ways: v Individually from a workstation. v As part of batch jobs. v As source statements to create a CL program or procedure. Commands can be entered individually from any command line or the Command Entry display. To simplify the use of CL, all the commands use a consistent syntax. In addition, the operating system provides prompting support for all commands, default values for most command parameters, and validity checking to ensure that a command is entered correctly before the function is performed. Thus, CL provides a single, flexible interface to many different system functions that can be used by different system users. Related concepts CL commands on page 6 A control language (CL) command is a single statement to request a system function.

Menus
The system provides a large number of menus that allow users to perform many system functions just by selecting menu options. Menus provide the following advantages: v Users do not need to understand CL commands and command syntax. v The amount of typing and the chance of errors are greatly reduced. Related information Application Display Programming i5/OS globalization

Messages
A message is a communication sent from one user, program, or procedure to another.

System i: Programming Control language

System messages can report both status information and error conditions. Most data processing systems provide communications between the system and the operator to handle errors and other conditions that occur during processing. The i5/OS operating system also provides message handling functions that support two-way communications between programs and system users, between programs, between procedures within a program, and between system users. Two types of messages are supported: v Immediate messages, which are created by the program or system user when they are sent and are not permanently stored in the system. v Predefined messages, which are created before they are used. These messages are placed in a message file when they are created, and retrieved from that file when they are used. Because messages can be used to provide communications between programs, between procedures in a program, and between programs and users, using the i5/OS message handling functions should be considered when developing applications. The following concepts of message handling are important to application development: v Messages can be defined in messages files, which are outside the programs that use them, and variable information can be provided in the message text when a message is sent. Because messages are defined outside the programs, the programs do not have to be changed when the messages are changed. This approach also allows the same program to be used with message files containing translations of the messages into different languages. v Messages are sent to and received from message queues, which are separate objects on the system. A message sent to a queue can remain on the queue until it is explicitly received by a program or workstation user. v A program can send messages to a user who requested the program regardless of what workstation that user has signed on to. Messages do not have to be sent to a specific device; one program can be used from different workstations without change. Related tasks Messages on page 452 Messages are used to communicate between users and programs. Related information i5/OS globalization Message descriptions: A message description defines a message to the i5/OS operating system. The message description contains the text of the message and information about replacement variables, and can include variable data that is provided by the message sender when the message is sent. Message descriptions are stored in message files. Each description must have an identifier that is unique within the file. When a message is sent, the message file and the message identifier tell the system which message description is to be used. Message queues: When a message is sent to a procedure, a program, or a system user, it is placed on a message queue associated with that procedure, program, or user. The procedure, program, or user sees the message by receiving it from the queue. The i5/OS operating system provides message queues for the following items: v Each workstation on the system v Each user enrolled on the system v The system operator v The system history log
Control language

Additional message queues can be created to meet any special application requirements. Messages sent to message queues are kept, so the receiver of the message does not need to process the message immediately.

CL commands
A control language (CL) command is a single statement to request a system function. Related concepts Control language on page 4 Control language (CL) is the primary interface to the operating system. CL can be used at the same time by users at different workstations, in batch and interactive jobs and in CL programs and procedures.

CL command names
The command name identifies the function that will be performed by the program that is called when the command is run. Most command names consist of a combination of a verb (or action) followed by a noun or phrase that identifies the receiver of the action (or object being acted on): (command = verb + object acted on). Abbreviated words, typically one to three letters, make up the command name. This reduces the amount of typing that is required to enter the command. For example, you can create, delete, or display a library; so the verb abbreviations CRT, DLT, and DSP are joined to the abbreviation for library, LIB. The result is three commands that can operate on a library: CRTLIB, DLTLIB, and DSPLIB. In another example, one of the CL commands is the Send Message command. You would use the Send Message (SNDMSG) command to send a message from a user to a message queue. The conventions for naming the combination verb and object commands are as follows: v The primary convention (as just shown) is to use three letters from each word in the descriptive command name to form the abbreviated command name that is recognized by the system. v The secondary convention is to use single letters from the ending word or words in the command title for the end of the command name, such as the three single letters DLO on the Delete Document Library Object (DLTDLO) command. v An occasional convention is to use single letters in the middle of the command name (typically between commonly used three-character verbs and objects), such as the letters CL in the Create CL Program (CRTCLPGM) command. Some command names consist of the verb only, such as the Move (MOV) command, or an object only, such as the Data (DATA) command. A few commands have an i5/OS command name, and can also be called using one or more alternate names that may be familiar to users of systems other than the i5/OS system. An alternate name is known as an alias, such as the name CD is an alias for the Change Current Directory (CHGCURDIR) command. Related concepts Simple and qualified object names on page 116 The name of a specific object that is located in a library can be specified as a simple name or as a qualified name. Object naming rules on page 118 These rules are used to name all i5/OS objects used in control language (CL) commands. The parameter summary table for each CL command shows whether a simple object name, a qualified name, or a generic name can be specified. Related reference

System i: Programming Control language

OBJTYPE parameter on page 83 The object type (OBJTYPE) parameter specifies the types of i5/OS objects that can be operated on by the command in which they are specified. Abbreviations of CL commands and keywords: Most CL command names that are part of the i5/OS operating system and other licensed programs that run on the operating system follow a consistent naming style. The first three letters of the command name (known as the command verb) represent the action that is being performed. The remaining letters of the command name describe the object that is having the action performed on it. Related tasks Defining commands on page 258 CL commands enable you to request a broad range of functions. You can use IBM-supplied commands, change the default values for command parameters, and define your own commands. CL command verb abbreviations: The majority of all CL commands use one of these common command verbs.
Verb abbreviation ADD CHG CRT DLT DSP END RMV STR WRK Meaning add change create delete display end remove start work with

The following table lists all the abbreviations that are used as command verbs.
Verb abbreviation ADD ALC ALM ANS ANZ APY ASK BLD CFG CHG CHK CLO CLR CMP CNL CPH CPR CPY CRT CVT Meaning add allocate alarm answer analyze apply ask build configure change check close clear compare cancel cipher compress copy create convert
Control language

Verb abbreviation DCP DLC DLT DLY DMP DSC DSP DUP EDT EJT EML ENC END EXP EXT FIL FMT FND GEN GRT HLD IMP INS INZ LNK LOD MGR MON MOV MRG OPN ORD OVR PAG PKG POS PRM PRT PWR QRY RCL RCV RGZ RLS RMV RNM RPL RQS RRT RSM RST RTV RUN RVK

Meaning decompress deallocate delete delay dump disconnect display duplicate edit eject emulate encipher end export extract file format find generate grant hold import install initialize link load migrate monitor move merge open order override paginate package position promote print power query reclaim receive reorganize release remove rename replace request reroute resume restore retrieve run revoke

System i: Programming Control language

Verb abbreviation SAV SBM SET SLT SND STR TFR TRC UPD VFY VRY WRK

Meaning save submit set select send start transfer trace update verify vary work with

CL command abbreviations: This table lists all abbreviations that are used in CL command names, including command verb abbreviations.
Command abbreviation A (suffix) ABN ACC ACCGRP ACG ACN ACNE ACT ADD ADM ADP ADPI ADPP ADPT ADR ADSM AFP AGR AGT AJE ALC ALR ALRD ALRTBL ALS ANS ANZ AP APAR APF APP APPC APPN APY ARA Meaning attributes abnormal access code access group accounting action action entry active, activity, activation add application development manager, administration, administrative adopt, adopting adapter information adapter profile adapter address ADSTAR distributed storage manager advanced function printing agreement agent autostart job entry allocate alert alert description alert table alias answer analyze access path authorized program analysis report advanced printer function application advanced program-to-program communications advanced peer-to-peer networking apply area
Control language

Command abbreviation ARC ASC ASK ASN ASP AST ATM ATN ATR AUD AUT AUTE AUTL BACK BAL BAS BCD BCH BCK BCKUP BGU BKP BKU BND BP BRM BSC BSCF BUF C CAL CALL CAP CBL CCS CCT CCTRTE CCTSRV CDE CDS CFG CFGL CFGLE CGY CHG CHK CHT CICS CL CLD CLG CLNUP CLO CLR

Meaning archive asynchronous ask association auxiliary storage pool assistance asynchronous transfer mode attention attribute audit, auditing authority authentication entry authorization list back balance, balancing BASIC language barcode batch backup backup business graphics utility breakpoint backup binding, bound boot protocol BRMS (backup recovery and media services) binary synchronous bsc file buffer C language calendar call capture COBOL language change control server IPX circuit circuit route circuit service code, coded coded data store configuration, configure configuration list configuration list entry category change check chart customer information control system control language C locale description catalog cleanup close clear

10

System i: Programming Control language

Command abbreviation CLS CLT CLU CMD CMN CMNE CMNF CMP CMT CNL CNN CNNL CNNLE CNR CNT CNV CODE COL COM COSD CP CPH CPIC CPP CPR CPT CPY CPYSCN CRG CRL CRP CRQ CRSDMN CRT CSI CSL CST CTG CTL CTLD CUR CVG CVN CVT D (suffix) DAT DB DBF DBG DCL DCP DCT DDI DDM

Meaning class client cluster command communications communications entry communications file compare commit cancel connection connection list connection list entry container contact conversation cooperative development environment collection community class-of-service description check pending cipher common programming interface for communications C++ language compress component copy copy screen cluster resource group crawler cryptographic change request cross-domain create communications side information console constraint, customization cartridge control controller description current coverage conversion convert description date database database file debug declare decompress dictionary distributed data interface distributed data management

Control language

11

Command abbreviation DDMF DEP DEV DEVD DFN DFT DFU DHCP DIR DIRE DIRSHD DKT DKTF DL DLC DLF DLFM DLO DLT DLY DMN DMP DNS DO DOC DOM DPCQ DPR DSC DSK DSP DSPF DST DSTL DSTLE DSTQ DSTSRV DTA DTAARA DTAQ DUP DWN E (suffix) EDT EDTD EDU EJT EML ENC END ENR ENV ENVVAR EPM

Meaning distributed data management file dependent device device description definition default data file utility dynamic host configuration protocol directory directory entry directory shadow diskette diskette file DataLink deallocate DataLink file DataLink file manager document library object delete delay domain dump domain name service do document Domino DSNX/PC queue DataPropagator Relational disconnect disk display display file distribution distribution list distribution list entry distribution queue distribution services data data area data queue duplicate down entry edit edit description education eject emulate, emulation encipher end enrollment environment environment variable extended program model

12

System i: Programming Control language

Command abbreviation ERR ETH EWC EWL EXIT EXP EXT F (suffix) FAX FCN FCT FCTE FD FFD FIL FILL FLR FMT FMW FNC FND FNT FNTRSC FNTTBL FORM FORMD FORMDF FR FRM FRW FTN FTP FTR GDF GEN GO GPH GPHPKG GRP GRT GSS HDB HDW HDWRSC HLD HLL HLP HLR HOST HST HTE HTTP I (suffix) ICF

Meaning error ethernet extended wireless controller extended wireless line exit expiration, expired, export extract file facsimile function forms control table forms control table entry file description file field description file fill folder format firmware finance find font font resource font table form form description form definition frame relay from firewall FORTRAN language file transfer protocol filter graphics data format generate go to graphics graph package group grant graphic symbol set host database hardware hardware resources hold, held high level language help holder host history, historical host table entry hypertext transfer protocol information, item, ILE intersystem communications function

Control language

13

Command abbreviation ICFF IDD IDLC IDX IDXE IFC IMG IMP INF INP INS INT INTR INZ IPI IPL IPS IPX IPXD ISDB ISDN ITF ITG ITM IWS JOB JOBD JOBE JOBQ JOBQE JRN JRNRCV JS JVA JVM KBD KEY L (suffix) LAN LANG LBL LCK LCL LCLA LF LFM LIB LIBL LIBM LIC LIN LIND LNK LNX

Meaning icf file interactive data definition utility ISDN data link control index index entry interface image import information input install internal machine intrasystem initialize internet protocol over IPX initial program load internet protocol over SNA internetwork packet exchange IPX description interactive source debugger integrated services digital network interactive terminal facility integrity item intelligent workstation job job description job entry job queue job queue entry journal journal receiver job scheduler Java Java virtual machine keyboard key list local area network language label lock local local attributes logical file logical file member library library list library member license, licensed line line description link Linux

14

System i: Programming Control language

Command abbreviation LOC LOCALE LOD LOF LOG LOGE LPD LPDA LPR LWS M (suffix) MAC MAIL MAP MAX MBR MDL MED MEDDFN MEDI MEM MFS MGD MGR MGTCOL MLB MLM MNT MNU MOD MODD MON MOV MRG MSF MSG MSGD MSGF MSGQ MST M36 M36CFG NAM NCK NDSCTX NET NETF NFS NODGRP NODL NTB NTF NTS NTW

Meaning location locale load logical optical file log log entries line printer daemon link problem determination aid line printer requester local workstation member message authentication code mail map maximum member model media media definition media information memory mounted file system managed migrate, migration, manager management collection media library media library media minutes, maintenance menu mode, module mode description monitor move merge mail server framework message message description message file message queue master AS/400 Advanced 36 machine AS/400 Advanced 36 machine configuration name nickname NetWare directory services context network network file network file system node group node list netbios NetFinity Notes NetWare

Control language

15

| |

Command abbreviation NWI NWS NWSAPP NWSCFG NWSD NWSH OBJ OCL OF OFC OFF OMC OPC OPN OPT ORD OUT OUTQ OUTQD OVL OVLU OVR OWN PAG PAGDFN PAGS PAGSEG PARM PART PASTHR PC PCD PCL PCO PCY PDF PDG PDM PEX PF PFD PFM PFR PFRG PFRT PFU PFX PGM PGP PGR PHS PIN PJ PJE

Meaning network interface network server network server application network server configuration network server description network server host adapter object operation control language optical file office off object management cycle opticonnect open optical, options order out, outgoing, output output queue output queue description overlay overlay utility override owner page, paginate page definition page segment page segment parameter part pass through personal computer pc document protocol pc organizer policy portable document format print descriptor group programming development manager performance explorer physical file printout format definition physical file member performance performance graphics performance tools print format utility prefix program primary group pager phase personal identification number prestart job prestart job entry

16

System i: Programming Control language

Command abbreviation PKG PLI PMN PMT PNLGRP POF POL POP PORT POS PPP PRB PRC PRD PRF PRFL PRJ PRM PRP PRS PRT PRTF PRTQ PRX PSFCFG PTC PTF PTP PTR PVD PVT PWD PWR PYM QM QRY QRYF QSH QST RBD RCD RCL RCV RCY RDAR RDB RDR REF REG REX RGP RGPE RGZ RJE

Meaning package PL/I (programming language one) permission prompt panel group physical optical file pool post office protocol port position point-to-point protocol problem procedure, processing product profile profile list project promote preparation personal print printer file print queue proxy print services facility configuration portable transaction computer program temporary fix point-to-point pointer provider private password power payment query management query query file Qshell interpreter question rebuild record reclaim receive recovery report/data archive and retrieval relational database reader reference registration REXX (restructured extended executor language) ranking group ranking group entry reorganize rje

Control language

17

Command abbreviation RLS RLU RMC RMT RMV RNM ROLL RPC RPDS RPG RPL RPT RPY RPYL RQS RRT RSC RSE RSI RSM RST RTD RTE RTGE RTL RTLF RTN RTV RUN RVK RWS RXC SAV SAVF SAVRST SBM SBS SBSD SCD SCDE SCHIDX SCHIDXE SCN SDA SDLC SEC SET SEU SFW SHD SHRPOOL SIGN SIT

Meaning release report layout utility report management cycle remote remove rename roll remote procedure call VM/MVS bridge (formerly Remote Spooling Communications Subsystem (RSCS)/PROFS distribution services) report program generator replace report reply reply list request reroute resource Remote Systems Explorer remote system information resume restore RouteD (TCP/IP) route entry routing entry retail retail file return retrieve run revoke remote workstation REXEC (remote execution) save save file save and restore submit, submitted subsystem subsystem description schedule schedule entry search index search index entry screen screen design aid synchronous data link control security set source entry utility software shadow, shadowing shared pool sign situation

18

System i: Programming Control language

Command abbreviation SLT SLTE SMG SMW SMTP SNA SND SNI SNMP SNPT SNUF SOC SPADCT SPL SPLF SPT SPTN SQL SRC SRCF SRV SRVPGM SSN SSND SST STC STG STGL STM STR STS SUBR SVR SWA SWL SYS SYSCTL SYSDIR SYSVAL S34 S36 S38 TAP TAPF TBL TBLE TCP TDLC TELN TFR TFTP THD THLD TIE

Meaning select, selection selection entry system manager system manager workstation simple mail transfer protocol systems network architecture send SNA over IPX simple network management protocol SNA pass through SNA upline facility sphere of control spelling aid dictionary spooling spooled file support support network structured query language source source file service service program session session description system service tools statistics storage storage link stream, statement start status subroutine server save while active stop word list system system control system directory system value System/34 System/36 System/38 tape tape file table table entry TCP/IP (transmission control protocol/internet protocol) twinaxial data link control telnet transfer trivial file transfer protocol thread threshold technical information exchange

Control language

19

Command abbreviation TIEF TIMZON TNS TO TOS TPL TRC TRG TRN TRP TXT TYPE T1 UBC UDFS UPD UPG USF USG USR USRIDX USRPRF USRPRTI USRQ USRSPC VAL VAR VFY VLDL VOL VRY VT VWS WAIT WCH WLS WNT WP WRK WSE WSG WSO WTR XREF X25

Meaning tie file time zone transaction to type of service template trace trigger token-ring network trap text type transport class 1 Ultimedia business conference user-defined file system update upgrade Ultimedia system facilities usage user user index user profile user print information user queue user space value variable verify validation list volume vary VT100 or VT220 virtual workstation wait watch wireless Windows NT word processing work with workstation entry workstation gateway workstation object writer cross-reference X.25

CL command keyword abbreviations: Each command parameter has a keyword name associated with it. The keyword name can be up to 10 characters.

20

System i: Programming Control language

Keyword names do not follow the same style as command names in that they do not necessarily begin with a command verb. Where possible, use a single word or abbreviation. For example, common keyword names in CL commands include OBJ (Object), LIB (Library), TYPE, OPTION, TEXT, and AUT (Authority). Construct a keyword name whenever using more than a single word or abbreviation to describe the parameter. Construct the keyword name by using a combination of standard command abbreviations and short unabbreviated words. For example, OBJTYPE is a common keyword name which combines the abbreviation OBJ with the short word TYPE. The two primary goals for keyword names are to be recognizable and to be consistent between commands that provide the same function. Use of simple words and standard abbreviations helps to make the keyword names recognizable. The following table contains a list of abbreviations that are used in CL command parameter keyword names.
Keyword Abbreviation A (suffix) ABS ABN AC ACC ACCMTH ACG ACK ACN ACP ACQ ACSE ACT ACTSNBU ADDR (or ADR) ADJ ADL ADM ADMD ADMDMN ADP ADPT ADR (or ADDR) ADV AFN AIX AJE AFN AFP ALC ALM ALR ALRD ALS ALW ANET ANS ANZ Meaning attributes, activity, address abstract, absolute abnormal autocall access, access code access method accounting acknowledge, acknowledgement action accept acquire association control service element active, activate, activation, activity, action activate switched network backup address adjacent, adjust additional administration, Application Development Manager administration domain administrative domain adopt, adaptive adapter address advance affinity AIX operating system autostart job entry affinity advanced function printing allocate alarm alert alert description alias allow adjacent network entity title answer analyze
Control language

21

Keyword Abbreviation AP APAR APF APPP APW APP APPC APPN APY ARA ARP ASC ASCII ASMT ASN ASP AST ASYNC ATD ATN (or ATTN) ATR (or ATTR) ATTACH ATTN (or ATN) ATTR (or ATR) AUD AUT AUTL AUTO AUX AVG AVL BAL BAS BCD BCH BCKLT BCKUP (or BKU) BDY BEX BGU BIN BIO BITS BKP BKT BKU (or BCKUP) BLDG BLK BLN BND BNR BOT BRK BSC

Meaning access path authorized program analysis report advanced printer function application process advanced print writer application advanced program-to-program communications advanced peer-to-peer networking apply area address resolution protocol asynchronous communications American National Standard Code for Information Interchange assignment assigned, association auxiliary storage pool assistance asynchronous attended attention attribute attached attention key attribute audit, auditing authority, authorized, authorization authorization list automatic auxiliary average available balance BASIC language, base barcode, broadcast data batch backlight backup boundary branch extender business graphics utility binary block input/output data bits breakpoint bracket, backout backup building block blinking cursor binding, bind, bound banner bottom break binary synchronous communications

22

System i: Programming Control language

Keyword Abbreviation BSCEL BSP BUF C CAB CAL CAP CB CBL CCD CCSID CCT CDE CDR CFG CFGL CFGLE CFM CGU CHAR (or CHR) CHAP CHG CHK CHKSUM CHKVOL CHL CHR (or CHAR) CHRSTR CHT CGY CKR CKS CL CLG CLN CLNS CLNUP (or CLN) CLO CLR CLS CLSF CLT CLU CMD CMN CMNE CMP CMT CNG CNL CNLMT (or CNNLMT) CNN CNNL CNNLMT

Meaning binary synchronous communications equivalence link backspace buffer C language cabinet calendar capacity, capture callback COBOL language call control data coded character set identifier circuit code call detail records configuration configuration list configuration list entry confirmation, confirm character generator utility character challenge-handshake authentication protocol change check checksum check volume identifier channel character character string chart category checker checksum control language catalog clean, cleaning, cleanup connectionless-mode network service cleanup close clear class class file client cluster command communications communications entry compare commitment, comment congestion cancel connection limit connection connection list connection limit

Control language

23

Keyword Abbreviation CNR CNS CNT CNTL (or CTL) CNTRY CNV COD CODPAG CODE COL COM COMPACT CON CONCAT COND CONS CONTIG CONT COS COSD COSTBYTE COSTCNN COVER CP CPB CPI CPL CPP CPR CPS CPT CPU CPY CPYRGT CRC CRDN CRG CRL CRQ CRQD CRSDMNK CRT CSI CSL CSR CST CTG CTL CTLD CTLP CTN CTS CTX CUR

Meaning container constant contact control country conversation code code page code, cooperative development environment column, collect, collection common, community compact, compaction confidential concatenation condition connection-mode network service contiguous continue class-of-service class-of-service description cost per byte cost per connection cover letter control point change profile branch, compatibility characters per inch complete C++ language compressed, compress call progress signal component central processing unit copy copyright cyclic redundancy check credentials charges, charging, cluster resource group correlation change request change request description cross-domain key create communications side information console cursor constraint, cost cartridge controller, control controller description control port contention clear to send context current

24

System i: Programming Control language

Keyword Abbreviation CVN CVR CVT CXT (or CTX) CYC D (suffix) DAP DAT DB DBCS DBF DBG DBR DCE DCL DCP DCT DDI DDM DDMF DDS DEC DEGREE DEL DEP DEPT DES DEST DEV DEVD DFN DFR DFT DFU DIAG DIF DIFF DIR DKT DLC DLO DLT DLVRY DLY DMN DMP DN DOC DPR DRAWER DRT DRV DSA DSAP

Meaning conversion cover convert, converting context cycle description directory access protocol date database double-byte character set database file debug database relations data communications equipment, distributed computing environment declare decompress dictionary distributed data interface distributed data management distributed data management file data description specification decimal parallel processing degree delivery dependent department data encryption standard destination device device description definition, defined defer default data file utility dialogue differences differentiated directory diskette deallocate document library object delete delivery delay domain dump distinguished name document DataPropagator Relational drawers direct drive directory systems agent destination service access point

Control language

25

Keyword Abbreviation DSB DSC DSK DSP DST DTA DTE DTL DUP DVL DWN E (suffix) EBCDIC ECN EDT EDU EIM EJT ELAN ELEM ELY EML ENB ENC ENR ENT ENV EOF EOR EOV ERR ESC EST ETH EVT EXC EXCH EXD EXEC EXIST EXN EXP EXPR EXT F (suffix) FAIL Fnn FA FAX FCL FCN FCT FCTE FEA

Meaning disable, disabled disconnect disk display daylight savings time, dedicated service tools, distribution data data terminal equipment detail duplicate development down entry extended binary-coded decimal interchange code explicit congestion notification edit education enterprise identity mapping eject ethernet LAN element early emulate, emulation enable encode enrollment enter, entries environment end of file end of record end of volume error escape establish, established ethernet event exclude exchange extend, extended executive existence extension expiration, expire expression extract, extend, extended file failure function key nn file attributes facsimile facilities function, functional forms control table forms control table entry front end application

26

System i: Programming Control language

Keyword Abbreviation FEA FEAT FID FIL FLD FLG FLIB FLR FLW FLV FMA FMT FNC FNT FORMDF FP FRAC FRC FRI FRM FRQ FSC FSN FST FTAM FTP FTR GC GCH GDF GDL GEN GID GIV GLB GNL GPH GRP GRT GSS GVUP HCP HDL (or HNDL) HDR HDW HEX HFS HLD HLL HLP HLR HNDL (or HDL) HPCP HPFCS

Meaning front end application feature file identifier file field flag files library folder flow failover font management aid format finance font form definition focal point fraction force Friday from, frame frequency fiscal file sequence number first file transfer, access, and management file transfer protocol (TCP/IP) filter garbage collection garbage collection heap graphics data file guideline, guidelines generate, generation group identifier number give global general graph group grant graphics symbol set give up host command processor handle header hardware hexadecimal hierarchical file systems hold, held high-level language help holder handle host to printer code page host to printer font character set

Control language

27

Keyword Abbreviation HPR HRZ HST HTML HTTP I (suffix) ICF ICV ID IDD IDL IDLC IDP IDX IE IFC IGC IGN IFC ILE IMG IN INAC (or INACT) INACT (or INAC) INC IND INF INFSKR INH INIT INL INM INP INPACING INQ INS INST INT INTNET INTNETA INTR INV INZ IP IPDS IPI IPL IPX ISDN ISP IT ITF ITM ITV

Meaning high performance routing horizontal history, historical hypertext markup language hypertext transfer protocol (TCP/IP) information, ILE intersystem communication function initial chaining value identifier interactive data definition idle integrated data link control interchange document profile index information element interface ideographic (double-byte character set) ignore interface Integrated Language Environment image input inactivity inactivity include indirect information Infoseeker inhibit initiate initial intermediate input inbound pacing inquiry install instance interactive, integer, internal internet internet address intrasystem invitee, inventory, invoke initialize, initialization internet protocol intelligent printer data stream IP over IPX initial program load internet packet exchange integrated services digital network internet service provider intermediate text, internal text interactive terminal facility item interval

28

System i: Programming Control language

Keyword Abbreviation IW2 J (suffix) JDFT JE (suffix) JFLD JORDER JRN JRNRCV JVA KBD KNW KPF KWD L (suffix) LADN LAN LANG (or LNG) LBL LCL LCLE LCK LDTIME LE (suffix) LEC LECS LEN LES LF LFM LFT LGL LIB LIBL LIC LIFTM LIN LMI LMT LNG (or LANG) LNK LNR LOC LOD LPI LRC LRG LRSP LST LTR LVL LWS LZYWRT M (suffix) MAC

Meaning IPX WAN version 2 protocol job join default job entry join field join file order journal journal receiver Java keyboard know, knowledge Kanji printer function keyword list library assigned document name local area network language label local local location entry lock lead time list entry LAN emulation client LAN emulation configuration server length LAN emulation server logical file logical file member left logical library library list license, licensed, licensed internal code lifetime line, line description local management interface limit language link listener location load lines per inch longitudinal redundancy check large local response list, last letter level local workstation lazy write member, messages macro, medium access control

Control language

29

Keyword Abbreviation MAINT MAJ MAP MAX MBR MBRS MCA MCH MDL MDM MDTA MED MEDI METAFILE MFR MFS MGR MGRR MGT MID MIN MLB MLT MM MNG MNT MNU MOD MODD MON MOV MQM MRG MRK MRT MSF MSG MSGS MSGQ MSR MSS MST MTD MTG MTU MTH MULT (or MLT) M36 M36CFG N (suffix) NAM NBR NCK NDE

Meaning maintenance major map, manufacturing automation protocol maximum member members message channel agent machine model modem message data media, medium media information metatable file manufacturer mounted file system manager manager registration management middle minimal, minimize media library device multiplier, multiple multimedia manage maintenance, mount, mounted menu mode, module mode description monitor, Monday move Message Queue Manager merge mark multiple requester terminal mail server framework message messages message queue measurement managed system services master mounted meeting maximum transmission unit method multiple AS/400 Advanced 36 machine AS/400 Advanced 36 machine configuration name, network name number nickname node

30

System i: Programming Control language

Keyword Abbreviation NDM NDS NEG NEP NET NFY NL NLSP NML NNAM (or NCK) NOD NODL NORM NOTVLD NPRD NRM NRZI NT NTB NTBD NTC NTF NTP NTS NTW NTW3 NUM NWI NWID NWS NWSD NXT OBJ OBS OFC OFSET OMT OPN OPR OPT ORD ORG ORGUNIT OS OSDB OUT OVF OVL OVR OVRFLW OWN PAD PAG PAL

Meaning normal disconnect mode NetWare directory services negative, negotiation never-ending program network notify network-layer NetWare link services protocol namelist nickname node node list normal not valid nonproductive normal, normal response mode non-return-to-zero-inverted network termination NetBIOS NetBIOS description notice NetFinity network time protocol Notes NetWare NetWare 3.12 numeric, number network interface network interface description network server network server description next object observable information office offset omit open operator, operating option, optical, optimum order organization, organizational organizational unit operating system object store database output overflow overlay override overflow owner, owned packet assembly/disassembly page, paginate product activity log

Control language

31

Keyword Abbreviation PARM PASTHR PBL PBX PC PCD PCL PCO PCS PCT PCTA PCY PDF PDG PDM PDU PENWTH PERS PF PFnn PFD PFM PFVLM PFR PFX PGM PGP PGR PHCP PHFCS PHS PHY PIN PJE PKA PKG PKT PL PLC PLL PLT PMN PMP PMT PND PNL PNT POL POLL POP PORT POS PPP PP

Meaning parameter pass-through probable private branch exchange personal computer PC document protocol PC organizer personal computer support percent personal computer text assist policy portable document format print descriptor group programming development manager protocol data unit pen width personal physical file program function key nn printout format definition physical file member physical file variable-length member performance prefix program primary group pager printer to host code page printer to host font character set phase physical personal identification number prestart job entry public key algorithm package packet presentation-layer place poll, polling plotter permission point-to-multipoint prompt pending panel point pool polled, polling post office protocol (TCP/IP) port number positive, position point-to-point protocol preprocessor

32

System i: Programming Control language

Keyword Abbreviation PPR PPW PRB PRC PRD PREBLT PRED PREEST PREF PREOPR PREREQ PRF PRI PRJ PRM PRMD PRN PRO PROC (or PRC) PROD PROP PRP PRS PRT PRTQ PRV PRX PSAP PSF PSN PSTOPR PTC PTF PTH PTL PTN PTP PTR PTY PUB PUNS PVC PVD PVT PWD PWR Q (suffix) QE (suffix) QLTY QOS QRY QST QSTDB QSTLOD

Meaning paper page printer writer problem procedure, procedural, process product, productive prebuilt predecessor pre-established preference, preferred pre-operation prerequisite profile, profiling primary project promote, parameters private management domain parent proposed procedure, processing production property/properties prepare, propagate, propagation personal print, printer print queue previous proxy presentation-layer service access point print services facility presentation post-operation protected, protection, portable transaction computer program temporary fix path partial partition, partitioning point-to-point pointer priority public punches permanent virtual circuit provider private password power queue queue entry quality quality of service query question question-and-answer database question-and-answer load

Control language

33

Keyword Abbreviation QUAL RAR RBD RCD RCDS RCL RCMS RCP RCR RCV RCY RDB RDN RDR RDRE REACT REASSM REC RECNN REF REINZ REL REP REQ (or RQS) RES RESYNC RET REX RFS RGS RGT RGZ RINZ RIP RJE RJT RLS RMD RMT RMV RNG RNM RPG RPL RPT RPY RQS (or REQ) RQT RRSP RRT RSB RSC RSL RSM

Meaning qualifier route addition resistance rebuild record records reclaim remote change management server recipient recursion, recurs receive recovery relational database relative distinguished name reader reader entry reactivation reassembly record reconnect reference reinitialize relations, release representation, representative required, request, requester resident, resolution resynchronize retention REXX language refuse, refused registration right reorganize reinitialize routing information protocol remote job entry reject release remind, reminder remote remove range rename RPG language replace, replacement report reply request, requester requisite remote response reroute reassembly resource, resources result, resolution resume

34

System i: Programming Control language

Keyword Abbreviation RSP RSRC RST RSTD RTE RTG RTL RTM RTN RTR RTT RTV RTY RU RVK RVS RWS SAA SADL SAP SAT SAV SAVF SBM SBS SCD SCH SCN SCT SDLC SDU SEC SEG SEGMENT SEL (or SLT) SENSITIV SEP SEQ SEV SFW SGN SHD SHF SHM SHR SHUTD SI SIG SIGN SIZ SL SLR SLT (or SEL) SMAE

Meaning response resource restore restricted route routing retail retransmit return, returned, retransmission router rotate retrieve retry request unit revoke reverse remote workstation systems application architecture saddle service access point Saturday save save file submit, submitted subsystem schedule, scheduled search screen sector synchronous data link control service data unit second, secure, security segment segmentation select, selection sensitivity separator sequence, sequential severity software sign-on shadow, shadowing shift short hold mode shared shutdown shift-in signature, signed sign-on size session-layer selector select, selection systems management application entity

Control language

35

Keyword Abbreviation SMG SMTP SMY SNA SNBU SND SNG SNI SNP SNPT SNUF SO SOC SP SPA SPC SPD SPF SPID SPL SPR SPT SPTN SPX SQL SRC SRCH (or SCH) SRM SRQ SRT SRV SSAP SSCP SSL SSN SSND SSP SST STAT STATION STC STD STG STK STM STMF STMT STN STP STPL STR STS STT STX

Meaning systems manager simple mail transfer protocol summary systems network architecture switched network back-up send single SNA over IPX snap SNA pass-through SNA upline facility shift-out sphere of control service processor spelling aid space, special supplied specific service provider identifier spooled, spooling superseded support, supported support network sequenced packet exchange structured query language source search system resource management system request sort service source service access point, session-layer service access point system services control point secure sockets layer session session description suspend system service tools statistical data records convenience station statistics standard storage stack stream stream file statement station step staple start, starting status state start-of-text character

36

System i: Programming Control language

Keyword Abbreviation SUB SUBADR SUBALC SUBDIR SUBFLR SUBNET SUBPGM SUBST SUCC SUN SURNAM SVC SVR SWL SWS SWT SWTSET SYM SYN SYNC SYS SYSLIBL S36 TAP TAPDEV TBL TCID TCP TCS TDC TDLC TEID TEL TELN TERM TFR TGT THD THLD THR THRPUT THS THU TIE TIM TIMMRK TIMO TIMOUT (or TIMO) TIMZON TKN TL TM TMN TMP

Meaning substitution, subject subaddress suballocation subdirectory subfolder subnetwork subprogram substitution successor Sunday surname switched virtual circuit server stop word list switches switch, switched switch setting symbol, symbolic syntax synchronous system system library list System/36 tape tape devices table transport connection identifier TCP/IP (transmission control protocol/internet protocol) telephony connection services telephony data collector twinaxial data link control terminal endpoint identifier telephone TELNET (TCP/IP) terminal transfer target thread threshold through, throughput throughput thesaurus Thursday technical information exchange time timemark timeout timeout time zone token transport-layer time transmission temporary

Control language

37

Keyword Abbreviation TMPL (or TPL) TMR TMS TMT TNS TOKN (or TKN) TOT TPDU TPL TPT TRANS TRC TRG TRM TRN TRNSPY TRP TRS TRUNC TSE TSP TSAP TSK TST TUE TWR TXP TXT TYP T1 T2 T4 UDFS UDP UI UID UNC UNL UNPRT UNQ UOM UPCE UPD UPG URL USG USR VAL VAR VCT VDSK VER (or VSN) VFY VLD

Meaning template timer transmission transmit transaction token total transport-layer protocol data unit template, topology transport transit, transaction trace trigger term token-ring network, translate transparency trap transit truncate timeslice end timestamp transport-layer service access point task test Tuesday tower transport text type transport class 1 transport class 2 transport class 4 user-defined file system user datagram protocol user interface, unnumbered information user identifier number unclassified unlink unprintable unique unit of measure universal product code type E barcode update upgrade uniform resource locator usage user value variable virtual circuit virtual disk version verify valid, validity, validation

38

System i: Programming Control language

Keyword Abbreviation VND VOL VRF VRT VRY VSN (or VER) VWS WAN WCH WDW WED WIN WK WNT WP WRD WRK WRT WS WSC WSCST WSE WSG WSO WTR WTRE WTRS X25 X31 X400 3270

Meaning vendor volume verification virtual vary version virtual workstation wide area network watch window Wednesday winner week Windows NT word processing word work, working write workstation workstation controller workstation customization object workstation entry workstation gateway (TCP/IP) workstation object writer writer entry writers X.25 X.31 X.400 3270 display

CL command parts
The parts of a command include a command label (optional), a command name (mnemonic), and one or more parameters. The parameter includes a keyword and a value. This figure illustrates the parts of a command:

CL command syntax: A command name and parameters make up each CL command.

Control language

39

The parameters used in CL commands are keyword parameters. The keyword, typically abbreviated the same way as commands, identifies the purpose of the parameter. However, when commands are entered, some keywords may be omitted by specifying the parameters in a certain order (positional specification). Commands have the following general syntax. The brackets indicate that the item within them is optional; however, the parameter set may or may not be optional, depending upon the requirements of the command.
[//] [?] [label-name:][library-name/]command-name [parameter-set]

Note: The // is valid only for a few batch job control commands, such as the DATA command. The // identifies those types of commands sent to the spooling reader that reads the batch job input stream. CL command label: Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. The label is typed just before the command name. The standard rules for specifying simple names (*SNAME) apply. The label is immediately followed by a colon. Blanks are allowed, though not required, between the colon and the command name. The label can contain as many as 10 characters, in addition to the colon. START: and TESTLOOP: are examples of command labels. Command labels are not required, but a label can be placed on any command. For labels that are placed on commands that cannot be run (for example, the Declare CL Variable (DCL) command), when the program branches to that label, the next command following the label is run. If the command following the label cannot be run, the program will move to the next command that can be run. Similarly, you can specify only one label on a line. If a command is not located on that line, the program will jump to the next command that can be run. To specify multiple labels, each additional label must be on a separate line preceding the command as shown:
LABEL1: LABEL2: CMDX

No continuation character (+ or -) is allowed on the preceding label lines. Related concepts Additional rules for unique names on page 124 Additional rules involve special characters (as an extra character) for object naming. Naming within commands on page 107 The type of name you specify in control language (CL) determines the characters you can use to specify a name. Communication names (*CNAME) on page 120 A communications name has a restrictive name syntax. It is typically used to refer to a device configuration object whose name length and valid character set is limited by one or more communication architectures. Names (*NAME) on page 120 When you create basic names and basic names in quoted form, follow these rules. Path names (*PNAME) on page 121 A path name is a character string that can be used to locate objects in the integrated file system.

40

System i: Programming Control language

Simple names (*SNAME) on page 123 Simple names are used for control language (CL) variables, labels, and keywords to simplify the syntax of CL. Simple names are the same as unquoted basic names but with one exception: periods (.) cannot be used. CL command parameters: Most CL commands have one or more parameters that specify the objects and values used to run the commands. When a command is entered, the user supplies the command object name, the parameter keyword names, and the parameter values used by the command. The number of parameters specified depends upon the command. Some commands (like the DO (Do) command and the ENDBCHJOB (End Batch Job) command) have no parameters, and others have one or more. In this topic, the word parameter typically refers to the combination of the parameter keyword and its value. For example, the Move Object (MOVOBJ) command has a parameter called OBJ that requires an object name to be specified. OBJ is the parameter keyword, and the name of the object is the value entered for the OBJ parameter. Related reference List of values on page 62 A list of values is one or more values that can be specified for a parameter. Required, optional, and key parameters on page 64 A CL command can have parameters that must be coded (required parameters) and parameters that do not have to be coded (optional parameters). Parameters in keyword and positional form on page 63 You can specify parameters in CL using keyword form, positional form, or in a combination of the two. Parameter values on page 55 A parameter value is user-supplied information that is used during the running of a command. CL command delimiters: Command delimiters are special characters or spaces that identify the beginning or end of a group of characters in a command. Delimiters are used to separate a character string into the individual parts that form a command: command label, command name, parameter keywords, and parameter values. Parameter values can be constants, variable names, lists, or expressions. The following figure shows various delimiters for a command.

The following delimiters are used in the i5/OS control language: v The colon (:) ends the command label, and it can be used to separate the command label from the command name.

Control language

41

v Blank spaces separate the command name from its parameters and separate parameters from each other. They also separate values in a list. Multiple blanks are treated as a single blank except in a quoted character string or comment enclosed in single quotation marks. A blank cannot separate a keyword and the left parenthesis for the value. v Parentheses ( ) are used to separate parameter values from their keywords, to group lists of values, and to group lists within lists. v Slashes (/) connect the parts of a qualified name or the parts of a path name. For a qualified object name, the two parts are the library qualifier and the object name (LIBX/OBJA). For a path name, the parts are the directory or directories searched and the object name (/Dir1/Dir2/Dir3/ObjA). v Either a period or a comma can be used as a decimal point in a decimal value (3.14 or 3,14). Only one decimal point is allowed in a value. v Single quotation marks specify the beginning and ending of a quoted character string, which is a combination of any of the 256 extended binary-coded decimal interchange code (EBCDIC) characters that can be used as a constant. For example, YOU CAN USE [email protected] ()*></ and lowercase letters is a valid quoted string that is a constant. Because a single quotation mark inside a quoted string is paired with the opening single quotation mark (delimiter) and is interpreted as the ending delimiter, a single quotation mark inside a quoted string must be specified as two single quotation marks. A pair of adjacent single quotation marks used this way is counted as a single character. v A special character is used to separate a date into three parts: month, day, and year (two parts for Julian dates: year and day). The special characters that may be used as date separators are the slash (/), the hyphen (-), the period (.), a blank ( ), and the comma (,). The special character used to code as separators in a command date must be the same as the special character specified as the date separator for the job. v The characters /* and */ can indicate the beginning and ending of a comment, or can be used in a character string. To begin a comment, the characters /* must begin in the first position of the command, be preceded by a blank, or be followed by either a blank or an asterisk. If the characters /* or */ occur in a later position of a command, they will typically be enclosed in single quotation marks and can represent, for example, all objects in the current directory for a path name. v A question mark (?) preceding the command name indicates that the command is prompted. If the command is specified with a label, the question mark may either precede the label, or it may follow the label and precede the command name. Within a CL program, when a question mark precedes a command name, a prompt display is presented. You can enter parameter values not specified on the command in the program. Prompting characters may be put into a command in two forms. A single question mark (?) may be coded before the command name (either before or after the command label in a CL program) to cause the entire command to be prompted. Selective prompt characters (?? or ?*) may be coded before any parameter keyword to cause that parameter to be prompted when the command is run. If a question mark is entered before the command name on the command entry display, the effect is the same as pressing the F4 (Prompt) key after the command is entered. Within a CL program, when a question mark precedes the command name, a prompt display is presented. This display is of the same format as that presented when pressing the F4 key from the command entry display. Parameters of the command for which the program has coded values are shown for informational purposes, but the user cannot change the values supplied by the program. Parameters for which no value was coded are shown as input fields so you can enter values to be used in processing the command. Selective prompting allows you to identify specific command parameters to be prompted. To call selective prompting, the characters ??, ?*, or ?- are coded immediately preceding the keyword name of the parameter(s) to be prompted.

42

System i: Programming Control language

Notes: 1. Selective prompting is not allowed with command string (*CMDSTR) parameters. 2. Parameters of the command that are preceded by the characters ?* are shown, but you cannot change the values that are supplied by the program. Parameters preceded by the characters ?? are shown as input fields containing the values coded in the program or command defaults so you can enter or change the values used in processing the command. Parameters preceded by the characters ?- are omitted from the display. All selectively prompted parameters must be coded in keyword or keyword-with-value form. Several parameters may be selectively prompted within one command. When selective prompting is called, only keywords that are immediately preceded by the selective prompt characters are prompted. All other parameters are processed using the values as coded on the command or, if not coded, using command defaults. Either form of prompting, but not both, is allowed on a single command in a CL program. If the character ? precedes the command name and selective prompt characters (except ?-) precede any keyword, an error message is returned and the program is not created. Related concepts Simple and qualified object names on page 116 The name of a specific object that is located in a library can be specified as a simple name or as a qualified name. CL command coding rules on page 45 This summary of general information about command coding rules can help you properly code CL commands. CL command definition parts on page 44 Command definition allows system users to create additional commands to meet specific application needs. These commands are similar to the system commands. Related tasks Specifying prompt control on page 294 You can control which parameters are displayed for a command during prompting by using prompt control specifications. Related reference Command definition statements on page 258 Command definition allows system users to create additional commands to meet specific application needs. Related information Integrated file system CL command continuation: Commands can be entered in free format. This means that a command does not have to begin in a specific location on a coding sheet or on the display. A command can be contained entirely in one record, or it can be continued on several lines or in several records. Whether continued or not, the total command length cannot exceed 32 702 characters. Either of two special characters, the plus sign (+) or the minus sign (-), is entered as the last non-blank character on the line to indicate that a command is continued. Blanks immediately preceding a + or - sign are always included; blanks immediately following a + or - in the same record are ignored. Blanks in the next record that precede the first non-blank character in the record are ignored when + is specified but are included when - is specified. The + is generally useful between parameters or values. At least one blank must precede the sign when it is used between separate parameters or values. The difference between the plus and minus sign usage is particularly important when continuation occurs inside a quoted character string.

Control language

43

The example that follows shows the difference.

CRTLIB LIB(XYZ) TEXT(This is CONT+ INUED) CRTLIB LIB(XYZ) TEXT(This is CONTINUED) For + : CRTLIB LIB(XYZ) TEXT(This is CONTINUED) For - : CRTLIB LIB(XYZ) TEXT(This is CONT INUED)

Notes: 1. The minus sign causes the leading blanks on the next line to be entered. 2. Use continuation characters + and - in CL programs only. An error occurs if + or - is used on a command entry display. 3. The characters + and - are used for multiple-command examples, but not for single-command examples. CL command comments: Comments within CL programs describe the expected behavior of the code. Comments can be inserted either inside or outside a commands character string wherever a blank is permitted. However, because a continuation character must be the last non-blank character of a line (or record), comments may not follow a continuation character on the same line. For readability, it is recommended that each comment be specified on a separate line preceding or following the command it describes, as shown here:
MOVOBJ OBJA TOLIB(LIBY) /* Object OBJA is moved to library LIBY. */ DLTLIB LIBX /* Library LIBX is deleted. */

Comments can include any of the 256 EBCDIC characters. However, the character combination */ should not appear within a comment because these characters end the comment. To begin a comment, the characters /* must be placed in the first position of the command, be preceded by a blank, or be followed by either a blank or an asterisk.

CL command definition parts

Command definition allows system users to create additional commands to meet specific application needs. These commands are similar to the system commands. Related concepts CL command delimiters on page 41 Command delimiters are special characters or spaces that identify the beginning or end of a group of characters in a command. Simple and qualified object names on page 116 The name of a specific object that is located in a library can be specified as a simple name or as a qualified name. CL command coding rules on page 45 This summary of general information about command coding rules can help you properly code CL commands. Related tasks Specifying prompt control on page 294 You can control which parameters are displayed for a command during prompting by using prompt control specifications.

44

System i: Programming Control language

Related reference Command definition statements on page 258 Command definition allows system users to create additional commands to meet specific application needs. Related information Integrated file system

CL command coding rules

This summary of general information about command coding rules can help you properly code CL commands.

CL command coding rules for delimiters

v Blanks are the basic separators between the parts of a command: Between command label and command name (not required, because the colon [:] is the delimiter). Between command name and first parameter, and between parameters. Between values in a list of values (not required between ending and beginning parentheses that enclose nested lists inside a list). Between the slashes and the name or label of some job control commands, like // DATA (not required). Blanks cannot separate a parameters keyword from the left parenthesis preceding its values. When a keyword is used, parentheses must be used to enclose the values; blanks can occur between the parentheses and the values. For example, KWD( A ) is valid. Multiple blanks are treated as a single blank, unless they occur in a quoted string or a comment. A colon must immediately follow a command label. Only one label can be used on any command (LABEL1: DCLF). Single quotation marks must be used to specify the beginning and end of a quoted character string. If a character string contains special characters, such as blanks, single quotation marks are required. If a single quotation mark must be used in the quoted string, two single quotation marks must be entered consecutively to indicate that it is a single quotation mark and not the end of the quoted string. Parentheses must be used: On parameters that are specified (coded) in keyword form To group multiple values in a single list, in a positional parameter, or around expressions To indicate a list (of none, one, or several elements) nested inside another list Sets of parentheses inside parentheses can be entered as long as they are paired, up to the maximum of five nested levels in logical expressions or three nested levels in lists of values. Comments can appear wherever blanks are permitted, except after a continuation character on the same line or record. A plus or minus sign at the end of a line indicates that the command is continued on the following line. Blanks following a + or - sign in the same record are ignored; blanks in the next record that precede the first non-blank character are ignored when + is specified and included when - is specified. One blank must precede the + sign when it is used between separate parameters or values.

v v v

v v v

CL command coding rules for parameters

v All required parameters must be coded. v If an optional parameter is not coded, the system uses its default value if the parameter has one. A default value is indicated by showing the value as bold and underlined text in the Choices column of the parameter summary table. v Words or abbreviations specified in capital letters in the command and parameter descriptions must be coded as shown. This is true of all command names, the keywords of parameters (if used), and many

Control language

45

parameter values. Lowercase letters not coded in quoted strings or in comments are translated to uppercase letters. Lowercase letters specified for values on parameters defined as CASE(*MIXED) are not translated to uppercase letters. v If there are key parameters, the values for the key parameters must be entered on the prompt before the remaining parameters will be shown. The Notes column in the parameter summary table indicates which parameters, if any, are key parameters. v Parameters cannot be coded in positional form past the positional parameter limit defined in the command object. The Notes column in the parameter summary table indicates which parameters may be specified in positional form.

CL command coding rules for parameter values

v The first character in all names must be an alphabetic character (A through Z, $, #, @, or a double quotation mark ()). Names must not exceed 10 characters (CL variable names and built-in function names can have 11 characters maximum, including the preceding & or % characters). In some commands, the names of objects can be specified in qualified form (library-name/object-name) or in path name form (directory-name/object name). v Predefined values that begin with an asterisk can be used only for the purposes intended, unless they are included in comments or quoted strings. These include predefined parameter values (*ALL, for example), symbolic operators (*EQ, for example), and the null value (*N). v In a CL program, a variable can be specified for all parameters, except where that is explicitly restricted. The user-specified value of the variable is passed as if it had been specified on the command. v In a CL program, a character string expression can be specified for any parameter defined with EXPR(*YES). The resulting value of the expression is passed as if the value had been specified on the command. v Null (omitted) values are specified with the characters *N, which mean that no value was specified and the default value, if one exists, should be used. *N is needed only when another value following the omitted value is being specified as a positional parameter or an element in a list. v Either a comma or a period can be used to indicate a decimal point in a numeric value. The decimal point is the only special character allowed between digits in the numeric string; there is no delimiter for indicating thousands. v When repetition is indicated for a parameter: A predefined value is not coded more than once in a series of values. As many user-defined values (like names or numeric limits) can be entered as there are different values or names, up to the maximum number of repetitions allowed. For example, if a parameter description states Up to 20 repetitions, you can specify a maximum of 20 values. Note: When you are using parameters that have the same name in different commands, the meaning of (and the values for) that parameter in each command may be somewhat different. Refer to the correct command description for the explanation of the parameter you are using. Related concepts CL command delimiters on page 41 Command delimiters are special characters or spaces that identify the beginning or end of a group of characters in a command. CL command definition parts on page 44 Command definition allows system users to create additional commands to meet specific application needs. These commands are similar to the system commands. Related reference Command definition statements on page 258 Command definition allows system users to create additional commands to meet specific application needs.

46

System i: Programming Control language

Commonly used parameters on page 65 Some parameters are commonly used in many CL commands. Parameters in keyword and positional form on page 63 You can specify parameters in CL using keyword form, positional form, or in a combination of the two. Parameter values on page 55 A parameter value is user-supplied information that is used during the running of a command.

CL command information and documentation

IBM provides documentation for CL commands. In addition, you can write documentation for your own commands. Related tasks Documenting command on page 324 If you define and create your own CL commands, you can also create online command help to describe your commands. CL command documentation format: Command documentation for CL commands is provided in the form of online help on the system and topics in the i5/OS Information Center. In the information center, each command description follows the same format. Each command description includes the parts discussed in the following subtopics. At the beginning of the command description documentation, there are links to the Parameters, Examples, and Error messages sections. It should be noted that, because a command is an i5/OS object, each command can be authorized for specific users or authorized for use by the public (all users authorized in some way to use the system). Because this is true for nearly every command, it is not stated in each command description. Related information iSeries Security Reference PDF CL environment classification: At the very top of the command description documentation is the environment classification. The environment classification describes where the command is allowed to run. Where allowed to run indicates in which environments the command can be entered. This information is the same information that is shown in the output of the Display Command (DSPCMD) command, which reflects what was specified for the ALLOW parameter when the command definition object was created. The Where allowed to run value includes the symbolic special values specified for the ALLOW parameter and a brief description that explains the environments where the command is allowed to run. The majority of commands are created with ALLOW(*ALL); *ALL is also the shipped default value for the ALLOW parameter. In this case, the description will be All environments (*ALL). For commands that must be run interactively, the ALLOW values specified when the command was created are typically (*INTERACT *IPGM *IREXX *EXEC) or (*INTERACT *IPGM *IMOD *IREXX *EXEC). In these two cases, the description shown will be Interactive environments (*INTERACT *IPGM *IREXX *EXEC) or Interactive environments (*INTERACT *IPGM *IMOD *IREXX *EXEC). For commands that are created to be run only in a compiled CL or interpreted REXX program, the ALLOW values specified when the command was created are typically (*BPGM *IPGM *BREXX *IREXX) or (*BPGM *IPGM *BMOD *IMOD *BREXX *IREXX). In these two cases, the description shown will be
Control language

47

Compiled CL program or interpreted REXX (*BPGM *IPGM *BREXX *IREXX) or Compiled CL or interpreted REXX (*BPGM *IPGM *BMOD *IMOD *BREXX *IREXX). If the combination of values specified for the ALLOW parameter when the command was created is not one of the previous combinations, a bulleted list is shown that gives a brief description of each value that was specified. v Batch job (*BATCH) v Interactive job (*INTERACT) v v v v v v v Batch ILE CL module (*BMOD) Interactive ILE CL module (*IMOD) Batch program (*BPGM) Interactive program (*IPGM) Batch REXX procedure (*BREXX) Interactive REXX procedure (*IREXX) Using QCMDEXEC, QCAEXEC, or QCAPCMD API (*EXEC)

Note: Some command definition objects shipped as part of the i5/OS operating system are not intended to be used as CL commands. For example, the CMD and PARM command definition objects are used in command definition source. These special-purpose command objects will not have any Where allowed to run information. Related concepts CL threadsafe classification The threadsafe classification indicates whether a command is threadsafe. Each command has a threadsafe classification. CL threadsafe classification: The threadsafe classification indicates whether a command is threadsafe. Each command has a threadsafe classification. The three types of threadsafe classifications are as follows: v Threadsafe: Yes This classification indicates that you can safely call the command simultaneously in multiple threads without restrictions. This classification also indicates that all functions called by this command are threadsafe. v Threadsafe: Conditional This classification indicates that not all functions provided by the command are threadsafe. The Restrictions section of the command provides information relating to thread safety limitations. Many commands are classified conditionally threadsafe because either some underlying system support is not threadsafe or the command can cause an exit point to be called. v Threadsafe: No This classification indicates that the command is not threadsafe and should not be used in a multithreaded program. While some thread unsafe commands may deny access, most thread unsafe commands do not. A diagnostic message, CPD000D, may be sent to the job log to indicate that a non-threadsafe command has been called. Whether the diagnostic message CPD000D is sent to the job log depends on the multithreaded job action attribute of the command; that attribute can be determined by using the Display Command (DSPCMD) command. The possible values and actions are: *SYSVAL - Action is based on system value QMLTTHDACN *RUN - Command runs. No messages are sent. *MSG - Diagnostic message CPD000D is sent to the job log. The command runs.

48

System i: Programming Control language

 *NORUN - Diagnostic message CPD000D is sent to the job log, and escape message CPF0001 is sent. The command does not run. If the command is run, the results are unpredictable. Note: Some command definition objects shipped as part of the i5/OS operating system are not intended to be used as CL commands. For example, the CMD and PARM command definition objects are used in command definition source. These special-purpose command objects will not have any Threadsafe information. Related concepts CL environment classification on page 47 At the very top of the command description documentation is the environment classification. The environment classification describes where the command is allowed to run. CL command description: The general description briefly explains the function of the command and any relationships it has with a program or with other commands. If there are restrictions on the use of the command, they are described under the heading Restrictions. The general description of the command follows the environment and threadsafe classification. CL parameters: The Parameters section provides a parameter summary table. The parameter summary table shows all the parameters and values that are valid for the command. Possible values are indicated in the Choices column. The default value, as shipped by IBM, is underlined in the Choices column. The default values are used by the system for parameters or parts of parameters that are not coded. Parameter descriptions Parameter descriptions follow the parameter summary table. Parameter descriptions are presented in the same order as the parameters are listed in the parameter summary table. Each parameter description includes an explanation of the function of the parameter, followed by a description of each possible parameter value. The default parameter value, if there is one, is typically described first and is shown as an underlined heading at the beginning of the text that describes the value. The description of each parameter explains what the parameter means, what it specifies, and the dependent relationships it has with other parameters in the command. When the parameter has more than one value, the information that applies to the parameter as a whole is covered first, then the specific information for each of the values is described after the name of each value. Parameter summary table The parameter summary table summarizes parameters and values for CL commands. Keyword column This column shows the parameter keyword name. Every CL command parameter has a keyword name associated with it. When you are viewing the command documentation using a browser, you can click on the keyword name to link to the start of the information for the parameter within the command documentation file. Description column

Control language

49

This column shows the prompt text defined for the parameter, a parameter qualifier, or a parameter element. Qualifiers are normally used for qualified object names or qualified job names. Elements are used to define multiple input fields for a single parameter. The description for a qualifier or element contains the qualifier or element number within the parameter. Choices column This column shows the possible values for the parameter, qualifier, or element. v Predefined values, also known as special values, are listed in this column. Predefined values typically begin with an asterisk (*) or Q, followed by all uppercase letters. v If the parameter, qualifier, or element allows user-defined values, a description of the parameter type appears in italics, for example Name. Default values may be defined for optional parameters. Default values are shown in bold, underlined text, for example *NO . v For complex parameters that have multiple qualifiers or elements, or if the parameter or element supports a list of values, any single value choices are identified. Single value choices may be used only once. v Repeated values can be specified for some parameters. For repeated values, this column indicates the number of allowed repetitions. v Notes column This column shows additional information about each parameter. v Required appears in this column to indicate required parameters, parameters for which you are always required to specify an input value. v Optional appears in this column to indicate optional parameters, parameters for which no input value is required. v Key appears in this column to indicate key parameters, which are used by commands that have prompt override programs. v Positional appears in this column if the parameter is allowed to be specified positionally (without the associated parameter keyword) in a command string. The parameters positional number appears following Positional. CL command coding examples: The Examples section provides at least one coded example for the command. Where necessary, several examples are provided for commands with many parameters and several logical combinations. For clarity, examples are coded in keyword form only. The same examples could be coded either in positional form or in a combination of keyword and positional forms, for commands that support one or more positional parameters. CL error messages: The Error messages section lists error messages that can be issued for the command. CL command help: All CL commands have online help available. Online help contains the parameter and value descriptions for the command. To display help for a command, do one of the following: v From an i5/OS command line, type the command name (for example, CRTUSRPRF) and press F1. The display shows general help for the command and help for each command parameter.

50

System i: Programming Control language

v From an i5/OS command line, type the command name (for example, CRTUSRPRF) and press F4 to display the command prompt display. On the prompt display, move the cursor to the top line and press F1. Printing CL command descriptions on the system: To print the parameter and value descriptions for a CL command, follow these instructions. To print help for an entire command, perform either of the following steps: v From any command line, type the command name (for example, CRTUSRPRF) and press F1. The display shows general help for the command and help for each command parameter. Press F14 to print the command help. v On a prompt display for a given command, move the cursor to the top line and press F1. Then press F14. To print the help for one CL command keyword parameter, perform the following steps: v From a command line, type the CL command name and press F4 to display the command prompt display. Position the cursor anywhere on the line of the keyword parameter for which you want help. Press F1 to display the help for the keyword parameter. Press F14 to print the help. Related reference Printable PDFs on page 2 Use this to view and print groups of CL commands or concepts. CL command prompters: Command prompters allow you to prompt for CL command parameters and values. Command prompters can be invoked directly or called from application programs. Using the prompters allows you to easily build syntactically correct CL command strings, because the prompters insert parameter keyword names and parameter delimiters, such as single quotation marks and parentheses, for you. The CL prompters also provide access to online command help, which can be used to describe the command, parameters and parameter values, command examples, and error messages signaled by the command. iSeries Navigator provides a graphical CL command prompter for use on a client PC. IBM eServer iSeries Access for Web provides an HTML form-based CL command prompter for use in a Web browser. The Remote System Explorer function also provides a graphical CL command prompter. The i5/OS operating system provides a CL command prompter that you can use from the command line by pressing F4. In addition, the Display Command Line Window (QUSCMDLN) API allows you display a command line from within an application.

CL commands that operate on i5/OS objects

Each of the i5/OS object types has a set of commands that operates on that object type. Most i5/OS object types have commands that perform the following actions: v Create (CRT): Creates the object and specifies its attributes. v Delete (DLT): Deletes the object from the system. v Change (CHG): Changes the attributes, contents of the object, or both. v Display (DSP): Displays the contents of the object. Display commands cannot be used to operate on objects. v Work with (WRK): Works with the attributes, contents of the object, or both. Unlike display commands, work commands allow users to operate on objects and modify applications.
Control language

51

Related reference CL commands that operate on multiple objects In addition to the commands that operate on single object types, there are commands that operate on several object types. These commands are more powerful because they can operate on several objects of different types at the same time.

CL commands that operate on multiple objects

In addition to the commands that operate on single object types, there are commands that operate on several object types. These commands are more powerful because they can operate on several objects of different types at the same time. For example: v Display object description (DSPOBJD or DSPLNK) displays the common attributes of an object. v Save object (SAVOBJ or SAV) saves an object and its contents on tape, optical media, or in a save file. v Restore object (RSTOBJ or RST) restores a saved version of the object from tape, optical media, or from a save file. Some of the commands operate on only one object at a time, but that object can be any one of several i5/OS object types. For example: v Move object (MOVOBJ or MOV) moves an object from one library or directory to another. v Rename object (RNMOBJ or RNM) specifies the new name of an object. The following tables list commands that perform an action on many of the object types.
Table 1. Commands operating on multiple object types (where object identified by object name, library and type) Item Object Actions ALC, CHK, CPR, CRTDUP, DCP, DLC, DMP, MOV, RNM, RST, SAV, SAVCHG, WRK, SET CHG DSP, EDT, GRT, RVK CHG, DSP, RTV CHG, END, STR WRK CHG, WRK CHG, WRK Identifier OBJ

Object access Object auditing Object authority

OBJACC OBJAUD OBJAUT OBJD JRNOBJ OBJLCK OBJOWN OBJPGP

Object description Object journaling Object lock Object owner Object primary group

Table 2. Commands operating on multiple object types (where object identified by path name) Item Object Object auditing Object authority Object description Object integrity Object journaling Object owner Object primary group Actions CPY, MOV, RNM, RST, SAV CHG CHG, DSP, WRK DSP, WRK CHK END, STR CHG CHG Identifier not applicable AUD AUT LNK OBJITG JRN OWN PGP

52

System i: Programming Control language

Related concepts CL commands that operate on i5/OS objects on page 51 Each of the i5/OS object types has a set of commands that operates on that object type. Related reference OBJTYPE parameter on page 83 The object type (OBJTYPE) parameter specifies the types of i5/OS objects that can be operated on by the command in which they are specified.

CL programs and procedures

CL programs and procedures are created from source statements that consist entirely of CL commands. The commands are compiled into either an original program model (OPM) program or an Integrated Language Environment (ILE) module that can be bound into programs made up of modules written in CL or other languages. Advantages of using CL programs and procedures include: v Using CL programs and procedures is faster than entering and running the commands individually. v CL programs and procedures provide consistent processing of the same set of commands and logic. v Some functions require CL commands that cannot be entered individually and must be part of a CL program or procedure. v CL programs and procedures can be tested and debugged like other high-level language (HLL) programs and procedures. v Parameters can be passed to CL programs and procedures to adapt the operations performed by the program or procedure to the particular requirements of that use. v You can bind CL modules with other ILE high-level language modules into a program. CL programs and procedures can be used for many kinds of applications. For example, CL procedures can be used to: v Provide an interface to the user of an interactive application through which the user can request application functions without an understanding of the commands used in the program or procedure. This makes the workstation users job easier and reduces the chances of errors occurring when commands are entered. v Control the operation of an application by establishing variables used in the application (such as date, time, and external indicators) and specifying the library list used by the application. This ensures that these operations are performed whenever the application is run. v Provide predefined routines for the system operator, such as procedures to start a subsystem, to provide backup copies of files, or to perform other operating functions. The use of CL programs and procedures reduces the number of commands the operator uses regularly, and ensures that system operations are performed consistently. Most of the CL commands provided by the system can be used in CL programs and procedures. Some commands are specifically designed for use in CL programs and procedures and are not available when commands are entered individually. These commands include: v Logic control commands that can be used to control which operations are performed by the program or procedure according to conditions that exist when the program or procedure is run. For example, if a certain condition exists, then do certain processing, else do some other operation. These logic operations provide both conditional and unconditional branching within the CL program or procedure. v Data operations that provide a way for the program or procedure to communicate with a workstation user. Data operations let the program or procedure send formatted data to and receive data from the workstation, and allow limited access to the database. v Commands that allow the program or procedure to send messages to the display station user.
Control language

53

v Commands that receive messages sent by other programs and procedures. These messages can provide normal communication between programs and procedures, or indicate that errors or other exceptional conditions exist. v The use of variables and parameters for passing information between commands in the program or procedure and between programs and procedures. v Commands that call other procedures. (Procedures cannot be called from the command line or in the batch job stream.) Using CL programs and procedures, applications can be designed with a separate program or procedure for each function, and with a CL program or procedure controlling which programs or procedures are run within the application. The application can consist of both CL and other HLL programs or procedures. In this type of application, CL programs or procedures are used to: v Determine which programs or procedures in the application are to be run. v Provide system functions that are not available through other HLL languages. v Provide interaction with the application user. CL programs and procedures provide the flexibility needed to let the application user select what operations to perform and run the necessary procedures. There are four types of CL programs and procedures: procedure, module, program, and service program.

CL procedure
A procedure is a set of self-contained high-level language statements that performs a particular task and then returns to the caller. In CL, a procedure typically begins with a PGM statement and ends with an ENDPGM statement.

CL module
A module is the object that results from compiling high-level language source statements using an Integrated Language Environment (ILE) compiler. A CL module is created by compiling CL source using the Create CL Module (CRTCLMOD) command. A module must be bound into a program to run. A CL module consists of two parts: A user-written procedure and a program entry procedure that is generated by the CL compiler. In other high-level languages (HLLs) (for example, C), a single module can contain multiple user-written procedures.

CL program
A control language (CL) program is a program that is created from source statements consisting entirely of CL commands. The operating system supports two types of programs: ILE program and OPM CL program. An ILE program is a program written in an Integrated Language Environment (ILE)-conforming high-level language. ILE programs are i5/OS objects that contain one or more modules. Modules cannot be run until they are bound into programs. These programs must have a program entry procedure. The CL compiler generates a program entry procedure in each module it creates. A single-module ILE program can be created using the Create Bound CL Program (CRTBNDCL) command. The Create Program (CRTPGM) command can be used to create an ILE program that contains module objects generated by different ILE compilers, including ILE CL. An OPM CL program is a program that conforms to the original program model (OPM). OPM CL programs are objects that result from compiling source using the Create CL Program (CRTCLPGM) command. Related information

54

System i: Programming Control language

ILE Concepts PDF

Service program
A service program is an i5/OS object that contains one or more modules. You can run programs that are not bound to service programs if they do not require any procedures from the service program. However, you cannot run any procedures from a service program unless that service program is bound to a program. In order to call procedures in a service program, you must export the procedure name. A service program is created using the Create Service Program (CRTSRVPGM) command While a program has only one entry point, a service program can have multiple entry points. You cannot call service programs directly. You can call procedures in a service program from other procedures in programs and service programs.

CL parameters
A parameter is a value that is passed to a command or program to provide user input or control the actions of the command or program.

Parameter values
A parameter value is user-supplied information that is used during the running of a command. An individual value can be specified in a constant value, a variable name, an expression, or a list of values. A parameter can specify one or a group of such values, depending on the parameters definition in a command. If a group of values is specified, the parameter is called a list parameter because it can contain a list of values. On commands with key and positional parameters, values can be specified in keyword form, positional form, or a combination of both forms. Parameter values must be enclosed in parentheses if any of the following conditions are true: v A keyword precedes the value. v The value is an expression. v A list of values is specified. Note: If only one value is specified for a list, no parentheses are required. Related concepts CL command coding rules on page 45 This summary of general information about command coding rules can help you properly code CL commands. Related reference CL command parameters on page 41 Most CL commands have one or more parameters that specify the objects and values used to run the commands. Constant value: A constant value is the actual value. The types of constants are character string (includes names, date and hexadecimal values), decimal, and logical. A constant value is an actual numeric value or a specific character string whose value does not change. Three types of constants can be used by the control language: character string (quoted or unquoted), decimal, and logical.

Control language

55

Character string: A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value. These EBCDIC values can include date and hexadecimal values. A character string can have two forms: quoted string or unquoted string. Either form of character string can contain as many as 5000 characters. A quoted character string is a string of alphanumeric and special characters that are enclosed in single quotation marks. For example, Credit limit has been exceeded is a quoted character string. The quoted string is used for character data that is not valid in an unquoted character string. For example, user-specified text can be entered in several commands to describe the functions of the commands. Those descriptions must be enclosed in single quotation marks if they contain more than one word because blanks are not allowed in an unquoted string. An unquoted character string is a string consisting of only alphanumeric characters and the special characters that are shown in the Unquoted String column in the following table. The table summarizes the main EBCDIC characters that are valid in unquoted and quoted character string values. An X in the last column indicates that the character on the left is valid; refer to the specific notes following the figure that indicate why the character is valid as described. The special characters allow the following to be unquoted character string values: v Predefined values (* at the beginning) v Qualified object names (/) v Generic names (* at the end) v Decimal constants (+, -, ., and ,) Any of these unquoted strings can be specified for parameters defined to accept character strings. In addition, some parameters are defined to accept predefined values, names, or decimal values either singly or in combinations.
Table 3. Quoted and unquoted character strings Name of character Ampersand Single quotation mark Asterisk (*) At sign Blank Colon Comma Digits Dollar sign Equal Greater than Left parenthesis Less than Letters (lowercase) Letters (uppercase) Minus : , 0-9 $ = > ( < a-z A-Z See Note 1 See Note 1 X See Notes 5, 8 See Notes 5, 8 See Note 4 See Notes 5, 8 See Note 2 X See Notes 1, 5 Character & * @ Unquoted string See Note 5 See Note 7 See Notes 5, 6 X Quoted string X X X X X X X X X X X X X X X

56

System i: Programming Control language

Table 3. Quoted and unquoted character strings (continued) Name of character Not Number sign Percent Period Plus Question mark Quotation marks Right parenthesis Semicolon Slash Underscore Vertical bar # % . + ? ) ; / _ | See Notes 3, 5 See Note 9 See Notes 5, 8 See Note 10 See Note 4 See Notes 1, 11 See Notes 1, 5 Character Unquoted string See Notes 5, 8 X Quoted string X X X X X X X X X X X X

Notes: 1. An unquoted string of all numeric characters, an optional single decimal point (. or ,), and an optional leading sign (+ or -) are valid unquoted strings. Depending on the parameter attributes in the command definition, this unquoted string is treated as either a numeric or character value. On the CALL command or in an expression, this unquoted string is treated as a numeric value; a quoted string is required if you want character representation. Numeric characters used in any combination with alphanumeric characters are also valid in an unquoted string. 2. In an unquoted string, lowercase letters are translated into uppercase letters unless the string is specified for a parameter that has the attribute CASE(*MIXED). 3. A slash can be used as a connector in qualified names and path names. 4. In an unquoted string, parentheses are valid when used to delimit keyword values and lists, or in expressions to indicate the order of evaluation. 5. In an unquoted string, the characters +, -, *, /, &, |, , <, >, and = are valid by themselves. If they are specified on a parameter that is defined in the command definition with the EXPR(*NO) attribute, they are treated as character values. If they are specified on a parameter that is defined in the command definition with the EXPR(*YES) attribute, they are treated as expression operators. 6. In an unquoted string, the asterisk is valid when followed immediately by a name (such as in a predefined value) and when preceded immediately by a name (such as in a generic name). 7. Because a single quotation mark within a quoted string is paired with the opening single quotation mark (delimiter) and is interpreted as the ending delimiter, an adjacent pair of single quotation marks () must be used inside a quoted string to represent a single quotation mark that is not a delimiter. When characters are counted in a quoted string, a pair of adjacent single quotation marks is counted as a single character. 8. In an unquoted string, the characters <, >, =, , and | are valid in some combinations with another character in the same set. Valid combinations are: <=, >=, =, >, <, ||, |<, and |>. If the combination is specified on a parameter that is defined in the command definition with the EXPR(*NO) attribute, it is treated as a character value. If it is specified on a parameter that is defined in the command definition with the EXPR(*YES) attribute, it is treated as an expression operator.

Control language

57

9. In an unquoted string, the underscore is not valid as the first character or when used by itself. 10. Quotation marks are used to delimit a quoted name. 11. A period is valid in a basic name, except as the first character. The following table contains examples of quoted string constants.
Table 4. Quoted string constants Constant 1,2, DONT 24 12 20 Value 1,2, DONT 24 12 20

The following table contains examples of unquoted string constants.

Table 5. Unquoted string constants Constant CHICAGO FILE1 *LIBL LIBX/PGMA 1.2 Meaning CHICAGO FILE1 Library list Program PGMA in library LIBX 1.2

Related reference Date values on page 59 A date value is a character string that represents a date. Hexadecimal values A hexadecimal value is a constant that is made up of a combination of the hexadecimal digits A through F and 0 through 9. Expressions on page 61 An expression is a group of constants or variables, separated by operators, that produces a single value. Character string expressions on page 101 The operands in a character string expression must be quoted or unquoted character strings, character variables, or the substring (%SUBSTRING or %SST) built-in function. Hexadecimal values: A hexadecimal value is a constant that is made up of a combination of the hexadecimal digits A through F and 0 through 9. All character strings except names, dates, and times can be specified in hexadecimal form. To specify a hexadecimal value, the digits must be specified in multiples of two, be enclosed in single quotation marks, and be preceded by an X. Examples are: XF6 and XA3FE. Note: Care should be used when entering hexadecimal values in the range of 00 through 3F, or the value FF. If these characters are shown or printed, they may be treated as device control characters producing unpredictable results. Related reference

58

System i: Programming Control language

Character string on page 56 A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value. Date values: A date value is a character string that represents a date. A date values format is specified by the system value QDATFMT. The length of the date value varies with the format used and whether a separator character is used. For example, if no separator character is used, the length of a date in a Julian format is five characters, and the length of a date in a non-Julian format is six characters. If a separator character is used, the length will be greater. The system value QDATSEP specifies the optional separator character that can be used when the date is entered. If a separator character is used, the date must be enclosed in single quotation marks. A date value can be specified for the parameters of type *DATE. A year value equal to or greater than 40 indicates a year from 1940 through 1999. A year value less than 40 indicates a year from 2000 through 2039. Related reference Character string on page 56 A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value. Related information System values Data separator (QDATSEP) system value Decimal values: A decimal value is a numeric string of one or more digits, optionally preceded by a plus (+) or minus (-) sign. A decimal value can contain a maximum of 15 digits, of which no more than nine can follow the decimal point (which can be either a comma or a period). Therefore, a decimal value can have no more than 17 character positions including the plus or minus sign and decimal point (if any). The following are examples of decimal values.

Logical values: A logical value is a single character (1 or 0) that is enclosed in single quotation marks. Logical values are often used as a switch to represent a condition such as on or off, yes or no, and true or false. When used in expressions, a logical value can be optionally preceded by *NOT or . The following are examples of logical values:

Control language

59

Table 6. Logical values Constant 0 1 Value 0 1 Meaning Off, no, or false On, yes, or true

Floating-point constants: A floating-point constant is a representation of a numerical constant, shown as an optional sign followed by one or more digits and a decimal point, which may be at the end. This representation consists of: v A significand sign: The significand sign may be + or -. The significand sign is optional; it is assumed to be + if no sign is specified. v A significand: The significand must contain a decimal point. The maximum number of digits that can be specified for the significand is 253; however, only the first 17 significant digits are used. v An exponent character: The exponent character must be E. v An exponent sign: The exponent sign must be + or -. The significand sign is optional; it is assumed to be + if no sign is specified. v An exponent: The exponent must be an integer; numbers 0 through 9 are valid. The maximum number of digits that can be specified is three. All floating-point constants are stored as double-precision values. No blanks are allowed between any of the parts of a floating-point constant, and the parts must be in the order listed previously. Some commands have parameters for which floating-point constants can be specified: v Call Program (CALL) or Call Procedure (CALLPRC) command: You can use the PARM parameter to pass a floating-point constant to a called program. Any program you call must receive a floating-point constant as a double precision value. v Change Program Variable (CHGPGMVAR) command: You can use the VALUE parameter to change a floating-point variable in a program. v Copy File (CPYF) command: You can use floating-point construction in the FROMKEY, TOKEY, and INCREL parameters to select which records are copied from a database file. Related information DDS Variable name: A variable contains a data value that can be changed when a program is run. A variable name is the name of the variable that contains the value. The variable is used in a command to pass the value that it contains at the time the command is run. The change in value can result if one of the following conditions occur: the value is received from a data area, a display device file field, or a message; the value is passed as a parameter; a Change Variable (CHGVAR) command is run in the program; or another program that is called changes the value before returning it. The types of variables are character string (includes names), decimal, logical, and integer. Decimal and logical values must match the type of value expected for the parameter. Character variables can specify any type of value. For example, if a decimal value is expected, it can be specified by a character variable as well as by a decimal variable.

60

System i: Programming Control language

The variable name identifies a value to be used; the name points to where the actual data value is. Because CL variables are valid only in CL programs, they are often called CL program variables or CL variables. CL variable names must begin with an ampersand (&). CL variables can be used to specify values for almost all parameters of CL commands. When a CL variable is specified as a parameter value and the command containing it is run, the current value of the variable is used as the parameter value. That is, the variable value is passed as if the user had specified the value as a constant. Because it is generally true that CL variables can be used for most parameters of commands in CL programs, the command descriptions typically do not mention CL variables. For parameters that are restricted to constants only (such as in the DCL command), to CL variables only (such as all of the parameters of the Retrieve Job Attributes (RTVJOBA) command), or to specific types of variables (such as on the RTVJOBA or Retrieve Message (RTVMSG) command), the individual parameter descriptions specify those limitations. Otherwise, if the command is allowed in a CL program, CL variables can be used in place of a value, even with parameters that accept only predefined values. For example, a KEEP parameter having only predefined values of *YES and *NO can have a CL variable specified instead; its value can then be changed to *YES or *NO, depending on its value when the command is run. A CL variable must contain only one value; it may not contain a list of values separated by blanks. The value of any CL program variable can be defined as one of the following types: v Character: A character string that can contain a maximum of 9999 characters. The character string can be coded in quoted or unquoted form, but only the characters in the string itself are stored in the variable. v Decimal: A packed decimal value that can contain a maximum of 15 digits, of which no more than nine can be decimal positions. v Logical: A logical value of 1 or 0 that represents on/off, true/false, or yes/no. v Integer: A two-byte or four-byte binary integer value that can be either signed (value may be positive or negative) or unsigned (value is always positive).
Table 7. CL program variables If value is: Name Date or time Character string Numeric Logical CL variable can be declared as: Character Character Character Decimal or integer or character Logical or character

Related concepts Additional rules for unique names on page 124 Additional rules involve special characters (as an extra character) for object naming. Expressions: An expression is a group of constants or variables, separated by operators, that produces a single value. The operators specify how the values are combined to produce the single value or result. The types of expressions are arithmetic, character string, relational, and logical. An expression can be used as a value for a CL command parameter only in CL programs and CL procedures.

Control language

61

The operators can be arithmetic, character string, relational, or logical. The constants or variables can be character, decimal, integer, or logical. For example, the expression (&A + 1) specifies that the result of adding 1 to the value in the variable &A is used in place of the expression. Character string expressions can be used in certain command parameters defined with EXPR(*YES) in CL programs. An expression can contain the built-in functions %BINARY (or %BIN), %SUBSTRING (or %SST), and %SWITCH. The types of expressions and examples of each are described there. Related concepts Symbolic operators on page 99 A variety of characters can be used as symbolic operators in CL commands. Related reference Character string on page 56 A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value. Expressions in CL commands on page 100 A character string expression can be used for any parameter, element, or qualifier that is defined with EXPR(*YES) in the command definition object. List of values: A list of values is one or more values that can be specified for a parameter. Not all parameters can accept a list of values. A list parameter can be defined to accept a specific set of multiple values that can be of one or more types. Values in the list must be separated by one or more blanks. Each list of values is enclosed by parentheses, indicating that the list is treated as a single parameter. Parentheses are used even when a parameter is specified in positional form. To determine whether a list can be specified for a parameter, and what kind of list it can be, refer to the parameter description under the appropriate command description. A list parameter can be defined to accept a list of multiple like values (a simple list) or a list of multiple unlike values (a mixed list). Each value in either kind of list is called a list element. List elements can be constants, variables, or other lists; expressions are not allowed. v A simple list parameter accepts one or more values of the type allowed by a parameter. For example, (RSMITH BJONES TBROWN) is a simple list of three user names. v A mixed list parameter accepts a fixed set of separately defined values that are in a specific order. Each value can be defined with specific characteristics such as type and range. For example, LEN(5 2) is a mixed list in which the first element (5) gives the length of a field and the second element (2) gives the number of decimal positions in that field. v For many parameters defined to accept lists, predefined single values can be specified in place of a list of values. One of these single values can be the default value, which can be either specified or assumed if no list is specified for a simple or mixed list. To determine what defaults are accepted for a given list parameter, refer to the description of the parameter in the description of the command for which the parameter is defined and used. Note: *N cannot be specified in a simple list, but it can be specified in a mixed list. Also, individual parameters passed on the CALL and CALLPRC commands cannot be lists. v The maximum level of nesting of lists inside lists is three, including the first. These are indicated by three nested levels of parentheses.

62

System i: Programming Control language

Here are examples of lists.

The last two examples contain two lists nested inside a list: the first list contains values of A and B, and the second list contains values of 1 and 2. The space between the two nested lists is not required. Blanks are the separators between the values inside each nested list, and the sets of parentheses group the nested values into larger lists. Related reference CL command parameters on page 41 Most CL commands have one or more parameters that specify the objects and values used to run the commands.

Parameters in keyword and positional form

You can specify parameters in CL using keyword form, positional form, or in a combination of the two.

Parameters in keyword form

A parameter in keyword form consists of a keyword followed immediately by a value (or a list of values separated by blank spaces) enclosed in parentheses. You cannot use blanks between the keyword and the left parenthesis preceding the parameter value. You can place blanks between the parentheses and the parameter value. For example, LIB(MYLIB) is a keyword parameter specifying that MYLIB is the name of the library that is used in some way, depending upon the command in which this LIB parameter is used. When command parameters are all specified in keyword form, they can be placed in any order. For example, the following two commands are the same:
CRTLIB CRTLIB LIB(MYLIB) TYPE(*TEST) TYPE(*TEST) LIB(MYLIB)

Parameters in positional form

A parameter in positional form does not have its keyword coded; it contains only the value (or values, if it is a list) whose function is determined by its position in the parameter set for that command. The parameter values are separated from each other and from the command name by one or more blank spaces. Because there is only one positional sequence in which parameters can be coded, the positional form of the previous CRTLIB (Create Library) command first example is:
Control language

63

CRTLIB

MYLIB

*TEST

If you do not want to enter a value for one of the parameters, the predefined value *N (null) can be entered in that parameters position. The system recognizes *N as an omitted parameter, and either assigns a default value or leaves it null. In the previous CRTLIB command second example, if you coded *N instead of *TEST for the TYPE parameter, the default value *PROD is used when the command is run, and a production library named MYLIB is created. The description of the CRTLIB command contains the explanation for each parameter. Notes: v Parameters cannot be coded in positional form beyond the positional coding limit. If you attempt to code parameters in positional form beyond that point, the system returns an error message. v Using positional form in your CL program source may save time when writing the program, but will be more difficult for you or someone else to maintain. Commands written using keyword form are generally easier to understand and enhance.

Combining keyword and positional forms

A CL command can also have its parameters coded in a combination of keyword and positional forms. The following examples show three ways to code the Declare CL Variable (DCL) command. Keyword form:
DCL VAR(&QTY) TYPE(*DEC) LEN(5) VALUE(0)

Positional form:
DCL &QTY *DEC 5 0

Positional and keyword forms together:

DCL &QTY *DEC VALUE(0)

In the last example, because the optional LEN parameter was not coded, the VALUE parameter must be coded in keyword form. Note: You cannot specify parameters in position form after a parameter specified in keyword form. Related concepts CL command coding rules on page 45 This summary of general information about command coding rules can help you properly code CL commands. Related reference CL command parameters on page 41 Most CL commands have one or more parameters that specify the objects and values used to run the commands.

Required, optional, and key parameters

A CL command can have parameters that must be coded (required parameters) and parameters that do not have to be coded (optional parameters). Optional parameters are typically assigned a system-defined default value if another value is not specified for the parameter when the command is entered. A command can also have key parameters which are the only parameters shown on the display when a user prompts for the command. After values are entered for the key parameters, the remaining parameters are shown with actual values instead of the default values (such as *SAME or *PRV).

64

System i: Programming Control language

Related reference CL command parameters on page 41 Most CL commands have one or more parameters that specify the objects and values used to run the commands.

Commonly used parameters

Some parameters are commonly used in many CL commands. These commonly used parameters meet one or both of the following criteria: v There is extensive information about how they are used. v They are used in many of the CL commands (such as the AUT parameter), and the parameter description in the individual command description gives only the essential information. The expanded descriptions of the applicable command parameters have been placed here for several reasons: v To reduce the amount of material needed in the individual commands. Normally programmers familiar with a parameters main function do not need the details. v To provide the supplemental information that is useful to programmers in some instances. The format for this information is designed for easy reference and includes a general description of each parameter that explains its function, states the rules for its use, and provides other helpful information. The values that can be specified for each parameter are also listed. Each value is followed by an explanation of what it means and (possibly) in which commands it is used. Not all of the values appear in every command. Refer to the individual command descriptions for the specific use of the value in that command parameter. Related concepts CL command coding rules on page 45 This summary of general information about command coding rules can help you properly code CL commands. AUT parameter: The authority (AUT) parameter is used in create, grant, and revoke commands. It specifies the authority granted to all users of an object. The AUT parameter also specifies an authorization list that is used to secure the object. Four object types allow the AUT parameter to contain an authorization list: LIB, PGM, DTADCT, and FILE. Public authority is an i5/OS object attribute that controls the base set of rights to that object for all users having access to the system. These rights can be extended or reduced for specific users. If you specify an authorization list, the public authority in the authorization list is the public authority for the object. The owner of an object has all authority to the object at its creation. If the object is created as a private object or with the limited authority given to all users, the owner can grant more or less authority to specific users by specifically naming them and stating their authority in the Grant Object Authority (GRTOBJAUT) command. The owner also can withdraw specific authority from specific users, or from all users (publicly authorized, specifically authorized, or both) by using the Revoke Object Authority (RVKOBJAUT) command or the Edit Object Authority (EDTOBJAUT) command. Values allowed *LIBCRTAUT The public authority for the object is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the object). The public authority is determined when the object is created. If the CRTAUT value for the library changes after the object is created, the new value does not affect any existing objects.
Control language

65

*USE

You can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. *USE authority provides object operational authority, read authority, and execute authority.

*CHANGE You can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. You can change and perform basic functions on the object. Change authority provides object operational authority and all data authority. *ALL You can perform all operations except those limited to the owner or controlled by authorization list management authority. Your can control the objects existence, specify the security for the object, change the object, and perform basic functions on the object. You also can change ownership of the object.

*EXCLUDE You cannot access the object. *EXECUTE You can run a program or procedure or search a library or directory. authorization-list-name Specify the name of the authorization list whose authority is used. Related information iSeries Security Reference PDF CLS parameter: The class (CLS) parameter identifies the attributes that define the run time environment of a job. The following attributes are defined in each class: v Run priority: A number that specifies the priority level assigned to all jobs running that use the class. The priority level is used to determine which job, of all the jobs competing for system resources, is run next. The value can be 1 through 99, where 1 is the highest priority (all jobs having a 1 priority are run first). v Time slice: The maximum amount of processor time that the system allows the job to run when it is allowed to begin. The time slice indicates the amount of time needed for the job to accomplish a meaningful amount of work (the time used by the system for reading auxiliary storage is not charged against the time slice). When the time slice ends, the job waits while other queued jobs of the same or higher priority are allowed to run (up to the time specified in their time slices); then the job is given another time slice. v Purge value: Indicates whether the job step is eligible to be moved from main storage to auxiliary storage while the job is waiting for some resource before it can continue, or when its time slice is used up and equal or higher priority jobs are waiting. v Default wait time: The default amount of time that the system waits for the completion of an instruction that performs a wait. This wait time applies to times when an instruction is waiting for a system action, not to the time an instruction is waiting for a response from a user. Normally, this would be the amount of time you are willing to wait for the system before ending the request. If the wait time is exceeded, an error message is passed to the job. This default wait time applies only when a wait time is not specified in the CL command that causes the wait. The wait time used for allocating file resources is specified in the file description and can be overridden by an override command. It specifies that the wait time specified in the class object is used. If file resources are not available when the file is opened, the system waits for them until the wait time ends.

66

System i: Programming Control language

Note: The class attributes apply to each routing step of a job. Most jobs have only one routing step, but if the job is rerouted (because of something like the Remote Job or Transfer Job command) the class attributes will be reset. v Maximum CPU time: The maximum amount of processor time (the sum of the time slices if they differ, or time slice period multiplied by number of time slices if they are equal) allowed for a jobs routing step to complete processing. If the jobs routing step is not completed in this amount of time, it is ended, and a message is written to the job log. v Maximum temporary storage: The maximum amount of temporary storage that can be used by a jobs routing step. This temporary storage is used for the programs that run in the job, for the system objects used to support the job, and for temporary objects created by the job. The system is shipped with a set of classes that define the attributes for several job processing environments. Other classes can be created by the Create Class (CRTCLS) command; any class can be displayed or deleted by the respective Display Class (DSPCLS) and Delete Class (DLTCLS) commands. Values allowed qualified-class-name Specify the name of the class, optionally qualified by the name of the library in which the class is stored. If the class name is not qualified and the CLS parameter is in the CRTCLS command, the class object is stored in *CURLIB; otherwise, the library list (*LIBL) is used to find the class name. Classes The following classes (by name) are supplied with the system: QGPL/QBATCH For use by batch jobs QSYS/QCTL For use by the controlling subsystem QGPL/QINTER For use by interactive jobs QGPL/QPGMR For use by the programming subsystem QGPL/QSPL For use by the spooling subsystem printer writer QGPL/QSPL2 For general spooling use in the base system pool COUNTRY parameter: The COUNTRY parameter specifies the country or region code. The country or region code is part of the X.400 O/R name. An ISO 3166 Alpha-2 code or an ITU-T country or region code can be specified. (The ITU-T country or region code is the data country or region or geographical area code published in the International Numbering Plan for Public Data Networks, Recommendation X.121 (09/92), by the ITU-T (formerly CCITT). The following table contains a list of the possible country or region codes that can be specified. Values allowed *NONE No country or region code is specified.

Control language

67

country-code Specify an ISO 3166 Alpha-2 code or a CCITT (also known as ITU-2) country or region code from the following table.
Table 8. ISO X.400 country or region codes Country or region Afghanistan Albania Algeria American Samoa Andorra Angola Anguilla Antarctica Antigua and Barbuda Argentina Armenia Aruba Australia Austria Azerbaijan Bahamas Bahrain Bangladesh Barbados Belarus Belgium Belize Benin Bermuda Bhutan Bolivia Bosnia and Herzegovina Botswana Bouvet Island Brazil British Indian Ocean Terr. Brunei Darussalam Bulgaria Burkina Faso Burundi Cambodia Cameroon ISO 3166 alpha-2 code AF AL DZ AS AD AO AI AQ AG AR AM AW AU AT AZ BS BH BD BB BY BE BZ BJ BM BT BO BA BW BV BR IO BN BG BF BI KH CM 528 284 613 642 456 624 724 652 736 344 722 283 362 505 232 400 364 426 470 342 257 206 702 616 350 631 ITU-T 1 country or region code 412 276 603 544

68

System i: Programming Control language

Table 8. ISO X.400 country or region codes (continued) Country or region Canada Cape Verde Cayman Islands Central African Republic Chad Chile China Christmas Island Cocos (Keeling) Islands Colombia Comoros Congo Cook Islands Costa Rica Cote dIvoire Croatia Cuba Cyprus Czech Republic Denmark Djibouti Dominica Dominican Republic East Timor Ecuador Egypt El Salvador Equatorial Guinea Eritrea Estonia Ethiopia Falkland Islands (Malvinas) Faroe Islands Fiji Finland France France, Metropolitan French Antilles French Guiana French Polynesia GF PF ISO 3166 alpha-2 code CA CV KY CF TD CL CN CX CC CO KM CG CK CR CI HR CU CY CZ DK DJ DM DO TP EC EG SV GQ ER EE ET FK FO FJ FI FR FX 340 742 547
Control language

ITU-T 1 country or region code 302, 303 625 346 623 622 730 460

732 654 629 548 712 612

368 280 230 238 638 366 370

740 602 706 627

248 636

288 542 244 208, 209

69

Table 8. ISO X.400 country or region codes (continued) Country or region French Southern Terr. Gabon Gambia Georgia Germany Ghana Gibralter Greece Greenland Grenada Guadeloupe Guam Guatemala Guinea Guinea-Bissau Guyana Haiti Heard and Mc Donald Islands Honduras China (Hong Kong S.A.R.) Hungary Iceland India Indonesia Iran Iraq Ireland Israel Italy Jamaica Japan Jordan Kazakhstan Kenya Kiribati Korea, Democratic Peoples Republic Korea, Republic of Kuwait Kyrgyzstan Lao Peoples Democratic Rep. ISO 3166 alpha-2 code TF GA GM GE DE GH GI GR GL GD GP GU GT GN GW GY HT HM HN HK HU IS IN ID IR IQ IE IL IT JM JP JO KZ KE KI KP KR KW KG LA 708 453, 454 216 274 404 510 432 418 272 425 222 338 440 - 443 416 401 639 545 467 450, 480, 481 419 437 457 535 704 611 632 738 372 628 607 282 262 - 265 620 266 202 290 352 ITU-T 1 country or region code

70

System i: Programming Control language

Table 8. ISO X.400 country or region codes (continued) Country or region Latvia Lebanon Lesotho Liberia Libyan Arab Jamahiriya Liechtenstein Lithuania Luxembourg China (Macau S.A.R.) Macedonia Madagascar Malawi Malaysia Maldives Mali Malta Marshall Islands Martinique Mauritania Mauritius Mayotte Mexico Micronesia Moldova, Republic of Monaco Mongolia Montenegro Montserrat Morocco Mozambique Myanmar Namibia Nauru Nepal Netherlands Netherlands Antilles New Caledonia New Zealand Nicaragua Niger
2 2

ISO 3166 alpha-2 code LV LB LS LR LY LI LT LU MO MK MG MW MY MV ML MT MH MQ MR MU YT MX FM MD MC MN ME MS MA MZ MM NA NR NP NL AN NC NZ NI NE

2 2

ITU-T 1 country or region code 247 415 651 618 606

246 270 455

646 650 502 472 610 278

609 617

334 550 259 212 428

354 604 643 414 649 536 429 204, 205 362 546 530 710 614
Control language

71

Table 8. ISO X.400 country or region codes (continued) Country or region Nigeria Niue Norfolk Island Northern Mariana Islands Norway Oman Pakistan Palau Panama Papua New Guinea Paraguay Peru Philippines Pitcairn Poland Portugal Puerto Rico Qatar Reunion Romania Russian Federation Rwanda St. Helena St. Kitts and Nevis St. Lucia St. Pierre and Miquelon St. Vincent and the Grenadines Samoa, Western San Marino Sao Tome and Principe Saudi Arabia Senegal Serbia
2

ISO 3166 alpha-2 code NG NU NF MP NO OM PK PW PA PG PY PE PH PN PL PT PR QA RE RO RU RW SH KN LC PM VC WS SM ST SA SN SP SC SL SG SK SI SB SO

2

ITU-T 1 country or region code 621

534 242 422 410

714 537 744 716 515

260 268 330 427 647 226 250, 251 635

356 358 308 360 549 292 626 420 608

Seychelles Sierra Leone Singapore Slovakia Slovenia Solomon Islands Somalia

633 619 525

540 637

72

System i: Programming Control language

Table 8. ISO X.400 country or region codes (continued) Country or region South Africa South Georgia and the S.S.I Spain Sri Lanka Sudan Suriname Svalbard and Jan Mayen Is. Swaziland Sweden Switzerland Syrian Arab Republic Taiwan Tajikistan Tanzania, United Republic of Thailand Togo Tokelau Tonga Trinidad and Tobago Tunisia Turkey Turkmenistan Turks and Caicos Islands Tuvalu Uganda Ukraine United Arab Emirates United Kingdom United States United States Minor Outlying Is. Uruguay Uzbekistan Vanuatu Vatican City State (Holy See) Venezuela Viet Nam Virgin Is. (Brit.) Virgin Is. (U.S.) Wallis and Futuna Is. Western Sahara ISO 3166 alpha-2 code ZA GS ES LK SD SR SJ SZ SE CH SY TW TJ TZ TH TG TK TO TT TN TR TM TC TV UG UA AE GB US UM UY UZ VU VA VE VN VG VI WF EH
Control language

ITU-T 1 country or region code 655

214 413 634 746

653 240 228 417 466 436 640 520 615

539 374 605 286 438 376

641 255 424, 430, 431 234, 235, 236, 237 310 - 316

748 434 541 225 734 452 348 332 543

73

Table 8. ISO X.400 country or region codes (continued) Country or region Yemen Yugoslavia, territories of the former Zaire Zambia Zimbabwe Notes: 1. This International Telecommunication Union (ITU) committee was formerly known as CCITT. 2. At the time of publication, the ISO 3166 Alpha-2 Code for this country or region could not be confirmed. Before using this code, be sure to confirm with the latest ISO 3166 standard. ISO 3166 alpha-2 code YE YU ZR ZM ZW ITU-T 1 country or region code 421, 423 220 630 645 648

FILETYPE parameter: The FILETYPE parameter specifies whether the database file description describes data records or source records. Further, the FILETYPE parameter specifies whether each member of a database file being created is to contain data records or source records (statements). For example, the file could contain RPG source statements for an RPG program or data description source (DDS) statements for another device or database file. Note: If you are creating a source type physical database file and are not providing field-level descriptions of the file (through data description specifications (DDS)), you can use either the Create Physical File (CRTPF) command or the Create Source Physical File (CRTSRCPF) command. However, the CRTSRCPF command is typically more convenient and efficient, because it is designed to be used to create source physical files. If DDS is provided when you are creating a source type database file, you should use the CRTPF command or the Create Logical File (CRTLF) command, which both have the SRCFILE and SRCMBR parameters for specifying source input. Records in a source file must have at least three fields: the first two are the source sequence number field and the date field; the third field contains the source statement. These three fields are automatically provided by the i5/OS operating system when a source file is created for which no DDS is provided; additional source fields can be defined in DDS. The length of the sequence number field must be six zoned digits with two decimal places. The length of the date field must be six zoned digits with no decimal places. The source sequence number and date fields are added to the source record when: v Records are read into the system. v Records are created by the Source Entry Utility (which is part of the licensed WebSphere Development Studio program). The fields are added when an inline data file (specified as the standard source file format) is read from the device. The spooling reader places a sequence number in the source sequence number field and sets up a zeroed date field. If those fields already exist in records read from the device, they are not changed. If the records in a database file are in source format and are being read as an inline data file in data format, the source sequence number and date fields are removed.

74

System i: Programming Control language

Values allowed *DATA The file created contains or describes data records. *SRC The file created contains or describes source records. If the file is keyed, the 6-digit source sequence number field must be used as the key field. Related information Database programming

FRCRATIO parameter: The force write ratio (FRCRATIO) parameter specifies the maximum number of records that can be inserted, updated, or deleted before they are forced into auxiliary (permanent) storage. The force write ratio ensures that all inserted, updated, or deleted records are written into auxiliary storage at least as often as this parameter specifies. In the event of system failure, the only records likely to be lost would be those that were inserted, updated, or deleted since the last force write operation. The force write ratio is applied to all records inserted, updated, or deleted in the file through the open data path (ODP) to which the force write ratio applies. If two programs are sharing the file, SHARE(*YES), the force write ratio is not applied separately to the set of records inserted, updated, or deleted by each program. It is applied to any combination of records (from both programs) that equals the specified force write ratio parameter value. For example, if a force write ratio of 5 was specified for the file, any combination of five records from the two programs (such as four from one program and one from the other) forces the records to be written to auxiliary storage. If two or more programs are using the file through separate ODPs, the insertions, updates, and deletions from each program are accumulated individually for each ODP. Each database file can have a force write ratio assigned to it. Logical files, which can access data from more than one physical file, can specify a more restrictive force write ratio (a smaller number of records) than that specified for the based-on physical files. However, a logical file cannot specify a less restrictive force write ratio. If a logical file specifies a less restrictive force write ratio than that specified for any of the physical files, the most restrictive force write ratio from the physical files is used for the logical file. For example, if the force write ratios of three physical files are 2, 6, and 8, the force write ratio of a logical file based on these physical files cannot be greater than 2. If no force write ratio is specified for the logical file, 2 is assumed. Thus, each time a program inserts, updates, or deletes two records in the logical file (regardless of which physical files are affected), those records are forced into auxiliary storage. The FRCRATIO number overrides the SEQONLY number specified. For example, if you specify:
OVRDBF ... SEQONLY(*YES 20) FRCRATIO(5)

The value of 20 is overridden and a buffer of five records is used. When FRCRATIO(1) is used, a buffer still exists, but it contains only a single record. Access paths associated with the inserted, updated, and deleted records are written to auxiliary storage only when all the records covered by the access path have been written to auxiliary storage. If only one ODP exists for the file, the access path is forced to auxiliary storage whenever a forced write occurs. If two or more ODPs to the file exist, the access path is written to auxiliary storage whenever all the inserted, updated, and deleted records for all the ODPs have been forced. Notes: 1. These rules apply only when a force write ratio of 2 or higher is specified. When a force write ratio of 1 is specified, the access path is not written to auxiliary storage until all the ODPs have been closed. 2. If the file is being recorded in a journal, FRCRATIO(*NONE) should be specified.
Control language

75

Values allowed *NONE There is no specified ratio; the system determines when the records are written to auxiliary storage. number-of-records-before-force Specify the number of updated, inserted, or deleted records that are processed before they are explicitly forced to auxiliary storage. Related information Journal management and system performance IGCFEAT parameter: The IGCFEAT parameter specifies which double-byte character set (DBCS) table is used, according to device and language. The following table indicates the corresponding IGCFEAT parameter and DBCS font table for the double-byte character set device being configured.
Table 9. DBCS features configurable on the IGCFEAT parameter Language/device Japanese Display Stations Type of physical DBCS workstation 5295-001 Display 5295-002 Display InfoWindow 3477-J Display PS/55 with 5250PC PS/55* with graphics 5250PC PS/55* with graphics 5250PC PS/55 with 5250PC/2 3270-type Display PS/55 with iSeries Access Attached to 5295-001 Display Attached to 5295-002 Display Attached to PS/55 5227-001 Printer 5327-001 Printer 5337-001 Printer 5383-200 Printer 5250-Type Display 3270-Type Display Configure as type-model 5555-B01 5555-B01 5555-B01, C01 5555-B01 5555-G01 5555-G02 5555-E01 3279-0 5555-B01 Configure with DBCS feature ((2424J4 55FE)) ((2424J4 68FE)) ((2424J4 68FE)) ((2424J4 68FE)) ((2424J4 68FE)) ((2424J4 68FE)) ((2424J0 (1))) ((2424J0 (1))) ((2424J0 (1)))

Japanese 24x24 Printers

5553-B01 5553-B01 5553-B01 ((2424J1 55FE)) ((2424J1 5553-B01 5553-B01 68FE)) ((2424J1 68FE)) ((2424J2 55FE)) ((2424J2 68FE)) 5553-B01 5583-200 5555-B01 3279-0 ((3232J0 (1))) ((3232J0 (1))) ((2424K0 (1))) ((2424K0 (1)))

Japanese 32x32 Printers Korean Display Stations Korean 24x24 Printers

Attached to 5295 Display 5553-B01 5553-B01 5553-B01 ((2424K0 (1))) ((2424K0 (1))) Attached to PS/55 5227-002 ((2424K2 52FE)) Printer 5555-B01 3279-0 ((2424C0)) ((2424C0))

Traditional Chinese Display 5250-Type Display Stations 3270-Type Display Traditional Chinese 24x24 Printers Simplified Chinese Display Stations Simplified Chinese 24x24 Printers

Attached to 5295 Display 5553-B01 5553-B01 5553-B01 ((2424C0)) ((2424C0)) Attached to PS/55 5227-003 ((2424C2 5CFE)) Printer 5250-Type Display 3270-Type Display 5555-B01 3279-0 ((2424S0)) ((2424S0)) ((2424S0)) ((2424S2 6FFE))

Attached to PS/55 5227-005 5553-B01 5553-B01 Printer

JOB parameter:

76

System i: Programming Control language

The JOB parameter specifies the name of the job to which the command is applied. The job name identifies all types of jobs on the system. Each job is identified by a qualified job name, which has the following format: job-number/user-name/job-name Note: Although the syntax is similar, job names are qualified differently than i5/OS object names. The following list describes the pieces of the qualified job name: v Job number: The job number is a unique 6-digit number that is assigned to each job by the system. The job number provides a unique qualifier if the job name is not otherwise unique. The job number can be determined by means of the Display Job (DSPJOB) command. If specified, the job number must have exactly six digits. v User name: The user name identifies the user profile under which the job is to run. The user name is the same as the name of the user profile and contains a maximum of 10 alphanumeric characters. The name can come from one of several sources, again, depending on the type of job: Batch job: The user name is specified on the SBMJOB command, or it is specified in the job description referenced by the BCHJOB or SBMJOB commands. Interactive job: The user name is specified at sign-on, or the user name is provided from the default in the job description referred to by the work stations job entry. Autostart job: The user name is specified in the job description referred to by the job entry for the autostart job. v Job name: The job name can contain a maximum of 10 alphanumeric characters, of which the first character must be alphabetic. The name can come from one of three sources, depending on the type of job: Batch job: The job name is specified on the Batch Job (BCHJOB) or Submit Job (SBMJOB) commands or, if not specified there, the unqualified name of the job description is used. Interactive job: The job name is the same as the name of the device (work station) from which the sign-on was performed. Autostart job: The job name is provided in the autostart job entry in the subsystem description under which the job runs. The job name was specified in the Add Autostart Job Entry (ADDAJE) command. Commands only require that the simple name be used to identify the job. However, additional qualification must be used if the simple job name is not unique. Duplicate job names If a duplicate job name is specified in a command in an interactive job, the system displays all of the duplicates of the specified job name to the user in qualified form. The job names are displayed in qualified form along with the user name and job number so that you can further identify the job that is to be specified in a command. You can then enter he correct qualified job name. If a duplicate job name is used in a command in a batch job, the command is not processed. Instead, an error message is written to the job log. The JOB parameter can have one or more of the following values, depending upon the command: Values allowed * The job is the one in which the command is entered; that is, the command with JOB(*) specified on it.

Control language

77

*JOBD The simple job name is the unqualified name of the job description. *NONE No job name is specified as in the Display Log (DSPLOG) command. job-name A simple job name is specified. qualified-job-name You must specify a qualified job name. If no job qualifier (user name and job number) is given, all of the jobs currently in the system are searched for the job name. If duplicates of the specified name are found, a qualified job name must be specified. Related concepts Simple and qualified object names on page 116 The name of a specific object that is located in a library can be specified as a simple name or as a qualified name. LABEL parameter: The LABEL parameter specifies the data file identifier of the data file on tape used in input and output operations. The data file can be in either the exchange format or the save/restore format. Note: The device file commands are used for tapes that are in the exchange format only, not for those in the save/restore format; user-defined device files are not used in save/restore operations. Each data file on tape has its data file identifier stored in its own file label. The data file label (or header label) of each data file is stored on the tape just before the data in the file. That is, each file on the tape has its own header label and its own data records together as a unit, and one file follows another. In addition to the data file identifier, each label also contains other information about the file, such as the file sequence number, record and block attributes, and whether it is a multivolume data file. Generally, the data file identifier is an alphanumeric character string that contains no more than 8 characters. However, the maximum length actually depends on several things: what data format is used for the files and CL commands in which the identifiers are specified. The unused portion of the file identifier field should be left blank. The first character of the data file identifier must be alphabetic (A through Z, $, #, or @) and the rest of the characters should be alphanumeric (A through Z, 0 through 9, $, #, _, ., and @). You can use special characters if the identifier is enclosed in single quotation marks. However, if the tape is used on an operating system other than i5/OS, the requirements for specifying identifiers must be considered. Tape data file identifiers Tape data file identifiers can have as many as 17 characters. However, if the tape is used on an operating system other than i5/OS, a maximum of 8 characters or a qualified identifier of no more than 17 characters should be used. If more than 8 characters are used, the identifier should be qualified and enclosed in single quotation marks so that no more than 8 characters occur in either part, and the parts are separated by a period; for example, LABEL(TAXES.JAN1980). This limitation applies to the following commands: Create Tape File (CRTTAPF), Change Tape File (CHGTAPF), Override Tape File (OVRTAPF), and Display Tape (DSPTAP). The data file identifier is put on the volume when the data file is put on the volume. For input/output operations, the identifier can be specified in one of tape device file commands, or it can be passed as a parameter when the device file is opened by the high-level language program that uses the file.

78

System i: Programming Control language

Save/restore format For tapes in the save/restore format, the identifier can have a maximum of 17 characters. If a library name is used to generate the label, the identifier cannot exceed 10 characters. You may specify a label other than a library name. Values allowed One of the following values can be specified for the LABEL parameter, depending upon the command. *ALL *NONE The data file identifier is not specified. It must be supplied before the device file, database file, or both are opened to be used in the tape operation. *SAME The data file identifier already present in the tape device file does not change. data-file-identifier Specify the identifier of the data file used or displayed with the device file description. *LIB The file label is created by the system and the name of the library specified on the LIB parameter is used as the qualifier for the file name. Labels for all the data file identifiers in the specified tape volumes are shown on the display.

*SAVLIB The file label is created by the system, and the name of the library specified on the SAVLIB parameter is used as the qualifier for the file name. LICOPT parameter: The Licensed Internal Code options (LICOPT) parameter allows you to specify individual compile-time options. This parameter is intended for the advanced programmer who understands the potential benefits and drawbacks of each selected type of compiler option. The following table shows the strings that are recognized by the Licensed Internal Code option (LICOPT) parameter. These strings are not case sensitive, but they are shown as mixed case for readability.
Table 10. LICOPT parameter strings String AllFieldsVolatile NoAllFieldsVolatile AllowBindingToLoadedClasses Description If set, treats all fields as volatile. If set, no fields are treated as volatile. Indicates that temporary class representations that were created as a result of defineClass calls within a running Java virtual machine may be tightly bound to other class representations within the same Java virtual machine. Indicates that temporary class representations that were created as a result of defineClass calls within a running Java virtual machine may not be tightly bound to other class representations within the same Java virtual machine. When multiple Java programs are generated for a JAR file, allows copies of classes from one program to be included in the generated code for another program. Facilitates aggressive inlining. Does not allow copies of classes from one program to be included in the generated code for another program.

NoAllowBindingToLoadedClasses

AllowClassCloning

NoAllowClassCloning

Control language

79

Table 10. LICOPT parameter strings (continued) String AllowInterJarBinding NoAllowInterJarBinding Description Allows tight binding to classes outside the class or JAR file being compiled. Facilitates aggressive optimizations. Does not allow tight binding to classes outside the class or JAR file being compiled. This overrides the presence of the CLASSPATH and JDKVER parameters on CRTJVAPGM. CRTJVAPGM uses multiple threads, if they are available, during creation. On multiprocessor systems this enables the use of more than one processor at a time, reducing the overall time required for a long CRTJVAPGM operation. However, the CRTJVAPGM will use more system resources, leaving fewer resources available for other applications. Indicates that CRTJVAPGM performs as usual, using only one thread. Performs analysis using visible classes to determine which objects are short-lived. A short-lived object does not outlive the method in which it is allocated, and may be subject to more aggressive optimizations. Does not perform analysis of short-lived objects. Indicates that class representations within a ZIP file or JAR file may be tightly bound to other class representations within the same ZIP file or JAR file. Indicates that class representations within a ZIP file or JAR file may not be tightly bound to other class representations within the same ZIP file or JAR file. Tells the translator that it is permitted to inline local methods. This is the default for optimization levels 30 and 40. Does not tell the translator that it is permitted to inline local methods. When the attributes of a field in an external class cannot be determined, this parameter generates code by assuming that the field is non-volatile. When the attributes of a field in an external class cannot be determined, this parameter generates code by assuming that the field is volatile. Specifies what action should be taken if, as a result of honoring the AssumeUnknownFieldsNonvolatile, PreresolveExtRef, or PreLoadExtRef Licensed Internal Code option, the Java virtual machine class loader detects that a class representation contains method representations, which cannot be used in the current context. Uses bound call to local init methods. Does not use bound call to local init methods. Uses bound call to local special methods. Does not use bound call to local special methods. Uses bound call to local static methods. Does not use bound call to local static methods. Binds trivial field references during program creation. Resolves field references at first touch. Uses bound call to local final virtual methods. Does not use bound call to local final virtual methods.

AllowMultiThreadedCreate

NoAllowMultiThreadedCreate AnalyzeObjectLifetimes

NoAnalyzeObjectLifetimes AllowBindingWithinJar

NoAllowBindingWithinJar

AllowInlining NoAllowInlining AssumeUnknownFieldsNonvolatile NoAssumeUnknownFieldsNonvolatile BindErrorHandling

BindInit NoBindInit BindSpecial NoBindSpecial BindStatic NoBindStatic BindTrivialFields NoBindTrivialFields BindVirtual NoBindVirtual

80

System i: Programming Control language

Table 10. LICOPT parameter strings (continued) String DeferResolveOnClass Description Takes a string parameter that is presumed to be the name of a class (for example, [Link]). When you set PreresolveExtRef to optimization level 40, classes that are specified with DeferResolveOnClass are not in the preresolve operation. This is useful if some classes in unused paths in the code are not in the CLASSPATH. It allows you to use optimization level 40 regardless of this by specifying a DeferResolveOnClass=[Link] for each missing class. Multiple DeferResolveOnClass entries are allowed. Allows CRTJVAPGM to use knowledge of the standard JDK to devirtualize calls to those JDK methods that are known to be final methods or members of final classes. It is the default at optimization levels 30 and 40. Does not allow CRTJVAPGM to use knowledge of the standard JDK to devirtualize calls to those JDK methods that are known to be final methods or members of final classes. Causes special code to be generated in the case of some recursive methods and eliminates much of the overhead of the recursive method calls. However, additional checking logic is generated on initial entry to the recursive method, so performance may not improve in cases of shallow recursion. Does not cause special code to be generated in the case of some recursive methods. Causes certain common subexpression optimizations to be disabled when generating code for certain types of integer expressions. This may improve overall optimization by exposing other optimization opportunities to the Optimizing Translator. Causes certain common subexpression optimizations to not be disabled when generating code for certain types of integer expressions. This generally results in better performing code at lower optimization levels. Performs extended basic block common subexpression elimination. Does not perform extended basic block common subexpression elimination. Performs local common subexpression elimination. Does not perform local common subexpression elimination. If set, generates code for castcheck that can be DAGed to an earlier instance. Is not set; does not generate code for castcheck that can be DAGed to an earlier instance. Runtime error reporting field**: Provides the option to fail the compile when encountering verification or class format errors. 0=Report all errors immediately; 0=Report all errors immediately; 1=Defer reporting of bytecode verification errors; 2=Defer reporting of bytecode verification errors and class format errors to runtime. Causes methods in cloned classes to be made internal, allowing the methods to be omitted if there are no references to them or if all references are inlined. The default is HideInternalMethods for optimization 40 and NoHideInternalMethods for optimization between 0 and 30. Causes the inlining of the [Link] method in some cases of scalar arrays.

DevirtualizeFinalJDK

NoDevirtualizeFinalJDK

DevirtualizeRecursive

NoDevirtualizeRecursive DisableIntCse

NoDisableIntCse

DoExtBlockCSE NoDoExtBlockCSE DoLocalCSE NoDoLocalCSE EnableCseForCastCheck NoEnableCseForCastCheck ErrorReporting

HideInternalMethods

InlineArrayCopy

Control language

81

Table 10. LICOPT parameter strings (continued) String NoInlineArrayCopy InlineInit NoInlineInit InlineMiscFloat NoInlineMiscFloat InlineMiscInt NoInlineMiscInt InlineStringMethods NoInlineStringMethods InlineTransFloat NoInlineTransFloat OptimizeJsr NoOptimizeJsr PreloadExtRef NoPreloadExtRef Description Prevents the inlining of the [Link] method. Inlines init methods for [Link] classes. Does not inline init methods. Inlines miscellaneous float/double methods from [Link]. Does not inline miscellaneous float/double methods. Inlines miscellaneous int/long methods from [Link]. Does not inline miscellaneous int/long methods. Permits inlining of certain methods from java/lang/String. Inhibits inlining of certain methods from java/lang/String. Inlines transcendental float/double methods from [Link]. Does not inline transcendental float/double methods. Generates better code for jsr bytecodes that have a single target. Suppresses generation of better code for jsr bytecodes that have a single target. Indicates that referenced classes may be preloaded (without class initialization) upon method entry. Indicates that referenced classes may not be preloaded upon method entry. However, the PreresolveExtRef parameter overrides this setting and causes referenced classes to be preloaded and initialized. Preresolves referenced methods at method entry. Resolves method references at first touch. Use to resolve class not found exceptions on programs that run on other machines. When a JAR file may be large enough to require multiple Java programs, this numeric value (default 100) is used to determine how large each program can grow. If set, attempt to short-circuit athrows. Is not set, does not attempt to short-circuit athrows. If set, recognizes some subclasses of Exception and short-circuit them directly. If not set, does not recognize some subclasses of Exception and short-circuit them directly. Inhibits floating-point optimizations that are not strictly compliant with the Java specification. Permits floating-point optimizations that are not strictly compliant with the Java specification.

PreresolveExtRef NoPreresolveExtRef ProgramSizeFactor

ShortCktAthrow NoShortCktAthrow ShortCktExSubclasses NoShortCktExSubclasses StrictFloat NoStrictFloat

The double asterisk (**) signifies that these strings require a numerical value for input in the syntax of stringname=number (with no spaces in between). MAXACT parameter: The maximum activity level (MAXACT) parameter specifies the maximum number of jobs that can be concurrently started and that remain active through a job queue entry, communications entry, routing entry, or workstation entry. A job is considered active from the time it starts running until it is completed. This includes time when:

82

System i: Programming Control language

v The job is actually being processed. v The job is waiting for a response from a workstation user. v The job is started and available for processing but is not actually using the processor. For example, it might have used up its time slice and is waiting for another time slice. v The job is started but is not available for processing. For example, it could be waiting for a message to arrive on its message queue. Values allowed *NOMAX There is no maximum number of jobs that can be active at the same time. maximum-active-jobs Specify a value that indicates the maximum number of jobs that can be concurrently active through this entry. Related information Work management OBJ parameter: The object (OBJ) parameter specifies the names of one or more objects affected by the command in which this parameter is used. If the OBJ parameter identifies objects that must exist in an i5/OS library, all of the objects must be in one of the following, depending upon which command is used: v the library specified in the LIB parameter, v the SAVLIB parameter, v the library qualifier in the OBJ parameter, v or the library part of the path name in the OBJ parameter On some commands, the generic name of a group of objects can be specified. To form a generic name, add an asterisk (*) after the last character in the common group of characters; for example, ABC*. If an * is not included with the name, the system assumes that the name is a complete object name. Values allowed Depending on the command, the following types of values can be specified on the OBJ parameter: v *ALL v Simple object name v Qualified object name v Generic object name v Qualified generic object name v Path name Related concepts Path names (*PNAME) on page 121 A path name is a character string that can be used to locate objects in the integrated file system. OBJTYPE parameter: The object type (OBJTYPE) parameter specifies the types of i5/OS objects that can be operated on by the command in which they are specified. The object types that can be specified in the OBJTYPE parameter vary from command to command.
Control language

83

The object-related commands allow you to perform general functions on most objects without knowing the special commands related to the specific object type. For example, you could use the Create Duplicate Object (CRTDUPOBJ) command to create a copy of a file or library instead of the specific commands Copy File (CPYF) or Copy Library (CPYLIB). Object-related commands This section lists commands containing the OBJTYPE parameter. See the information for the individual commands listed to find out which object types can be operated on using the commands. The following commands contain the OBJTYPE parameter but operate on only a few object types. v CHKDLO operates on *DOC and *FLR. v CPROBJ and DCPOBJ operate on *FILE, *MENU, *MODULE, *PGM, *PNLGRP, and *SRVPGM. v CRTSQLPKG operates on *PGM and *SRVPGM. v DSPPGMADP operates on *PGM, *SQLPKG, and *SRVPGM. v DSPPGMREF operates on *PGM and *SQLPKG. v RSTCFG operates on *CFGL, *CNNL, *COSD, *CTLD, *DEVD, *LIND, *MODD, and *NWID. v SAVLICPGM operates on *LNG and *PGM. v SETOBJACC operates on *FILE and *PGM. The DSPLNK and WRKLNK commands operate on all object types. The ALCOBJ and DLCOBJ commands also require that an object type value is specified. However, for these commands, the object type value is specified as one of four values (in a list of values) on the required parameter OBJ. The following object-related commands operate on many object types.
Object CHGOBJD CHKOBJ CRTDUPOBJ DSPOBJD MOVOBJ RNMOBJ RTVOBJD WRKOBJ Object authority CHGOBJAUD CHGOBJOWN CHGOBJPGP DSPOBJAUT EDTOBJAUT GRTOBJAUT RVKOBJAUT Save/restore Journal Other DMPOBJ DMPSYSOBJ PRTDSKINF WRKOBJLCK

RSTOBJ SAVCHGOBJ CHGJRNOBJ SAVOBJ ENDJRNOBJ STRJRNOBJ

Related concepts External object types on page 112 Many types of external objects are stored in libraries. Related reference CL command names on page 6 The command name identifies the function that will be performed by the program that is called when the command is run. Most command names consist of a combination of a verb (or action) followed by a noun or phrase that identifies the receiver of the action (or object being acted on): (command = verb + object acted on). TEXT parameter on page 91 The TEXT parameter specifies the user-defined description that briefly describes the object that is being created or changed. CL commands that operate on multiple objects on page 52 In addition to the commands that operate on single object types, there are commands that operate on several object types. These commands are more powerful because they can operate on several objects of different types at the same time.

84

System i: Programming Control language

OUTPUT parameter: The OUTPUT parameter specifies whether the output from the display command is displayed, printed, or written to an output file. Basically, the same information is provided whether the output is displayed, printed, or written; only the format is changed as necessary to present the information in the best format for the device. For example, because there are more lines on a printed page than on a display, column headings are not repeated as often in printed output. If the output is to be shown on the display, it will be sent to the workstation that issued the display command. It will be shown in the format specified in the display device file used by that display command. A different device file is used for the output of each display command, and the file is different for displayed, printed, or written file output. In most cases, the name of the command is part of the file names of either type of device file. If the output will be printed, it is spooled and an entry is placed on the jobs output queue. The output can be printed depending on which device is specified in the Start Printer Writer (STRPRTWTR) command. Note: Although the IBM -supplied printer files are shipped with SPOOL(*YES) specified, they can be changed to SPOOL(*NO) by the Override with Printer File (OVRPRTF) and Change Printer File (CHGPRTF) commands. If the OUTPUT parameter is not specified in the display command, the default value * is assumed. The output resulting from this value depends on the type of job that entered the command. The following table shows how the output is produced for interactive and batch jobs.
Table 11. Output for interactive and batch Output * *PRINT Interactive job Displayed Printed Batch job Printed Printed

Values allowed * Output requested by an interactive job is shown on the display. Output requested by a batch job is printed with the jobs spooled output.

*PRINT The output is printed with the jobs spooled output. *OUTFILE The only output is to be written to a specified database file. PRTTXT parameter: The print text (PRTTXT) parameter specifies the text that appears at the bottom of listings and on separator pages. Print text is copied from the job attribute when the job enters the system. Print files that originate on another system do not use the print text on the target system. Print text exists as a job attribute (PRTTXT) for defining the print text of a specific job, and as a system value (QPRTTXT) for the default of jobs with *SYSVAL specified. QPRTTXT is the system-wide default for all jobs. The print text can be up to 30 characters in length. The text should be centered in the forms width and printed in the overflow area. You should center the required text within the 30 character field.
Control language

85

If the print text is not blank, the system prints 30 characters of text on the bottom of each page. This text normally follows the overflow line and is preceded by a blank line (if the forms length permits). If the user prints past the overflow line, the print text follows the last line of the user text, again preceded by a blank line when possible. If the overflow line is the last line of the form, the print text also prints on the last line of the form, which may result in the typing over of user text. The print text for job and file separators is put on the first line of the separator page. A job separator contains print text of the job that created the separator at the time the file was printed. A file separator contains the same print text as the spooled file it precedes. The print text can be specified for all job types. System and subsystem monitor jobs use the system value. Reader and writer jobs use the system value unless print text is changed in the QSPLxxxx job description associated with the reader or writer. The print text is determined from several places by using the following hierarchical order. If print text is not specified in one place, the next place in the order is used. The hierarchical order, beginning with the highest priority, is as follows: v Override print file value v Print file value v Job attribute changed by the Change Job (CHGJOB) command v Job attribute set by the Submit Job (SBMJOB) or Batch Job (BCHJOB) command v Job description v System value Values allowed For the system value QPRTTXT, any character string can be specified, with the exception of *SYSVAL. If *BLANK is specified, there will be no print text. For PRTTXT, some of the following values can be selected, depending on the command: *SAME The print text does not change. *CURRENT The print text is taken from the submitting job. *JOBD The print text is taken from the job description under which the job is run. *SYSVAL The print text is taken from the system value QPRTTXT. *BLANK There is no text or blanks printed. print-text Specify 30 characters of text. If there are blanks in the text, then single quotation marks must be used around the entry. The text should be centered within the field for the text to be centered on the page. REPLACE parameter: The replace (REPLACE) parameter is used on create commands. It specifies that the existing object, if one exists, is replaced by the object of the same name, library, and object type that is being created. The user of the new object is granted the same authority as for the object being replaced. If the object being replaced is secured by an authorization list, then the new object is secured by the same

86

System i: Programming Control language

authorization list. The public authority of the new object is the same as the public authority of the replaced object. The AUT parameter from the create command is ignored. All private authorities from the replaced object are copied to the new object. The owner of the new object is not copied from the replaced object. The owner of the new object is the creator of the new object or the creators group profile. Some objects such as panel groups, display files, and menus cannot be replaced if they are in use by the current job or another job. If the object being created is a program or service program, then the user profile (USRPRF parameter) value from the replaced program is used. The user profile (USRPRF parameter) value from the Create Program (CRTPGM) or Create Service Program (CRTSRVPGM) command is ignored. If the value of the user profile (USRPRF parameter) of the program or service program being replaced is *OWNER, then only the current owner of the program or service program being replaced can create the new program or service program that replaces the existing program or service program. If the owner of the existing object and the object being created do not match, the object is not created and message CPF2146 is sent. If the object being created is a program or service program, then the use adopted authority (USEADPAUT) value from the replaced program or service program is used as long as the user creating the object can create programs/service programs with the USEADPAUT(*YES) attribute. The QUSEADPAUT system value determines whether users can create programs or service programs to use adopted authority. For example, if the existing object being replaced has USEADPAUT(*YES) and you do not have authority to create a program or service program that uses adopted authority, the program or service program created will have USEADPAUT(*NO). In this case, the USEADPAUT value was not copied. If you have authority to create programs or service programs that use adopted authority, the created program or service program will have the same USEADPAUT value as the program or service program being replaced. An informational message is sent which indicates whether the USEADPAUT value was copied to the object being replaced. If the object being created is a file, and the default, or *YES, is specified on the REPLACE parameter, an existing device file other than save file and a DDM file with the same qualified name will be replaced by the new file. For example, an existing display file can be replaced by a new printer file, tape file, and so on. Object management (*OBJMGT), object existence (*OBJEXIST), and read (*READ) authorities are required for the existing object to allow replacement of the existing object with a new object. The existing object is renamed and moved to library QRPLOBJ or library QRPLxxxxx if the object resides on an Independent ASP (where xxxxx is the number of the primary ASP of the ASP group) when the creation of the new object is successful. The replaced object is renamed with a Q appended to a time stamp and moved to library QRPLOBJ or library QRPLxxxxx if the object resides on an Independent ASP. If the existing object could not be moved to the QRPLOBJ library because QRPLOBJ was locked by another job, for example, the existing object will be moved to the QTEMP library for the job. If the existing object could not be moved to the QTEMP library for the job, the existing object will be deleted. If the existing object could not be moved to the QRPLxxxxx library because QRPLxxxxx was locked by another job, for example, the existing object will be deleted. Restriction Programs can be replaced while they are being run; however, if the replaced program refers to the program message queue after the renaming of the replaced program to the Qtimestamp name, the program fails and an error message is sent stating that the program message queue is not found. A database file, physical or logical, and a save file cannot be replaced by any file. Library QRPLOBJ is cleared when an initial program load (IPL) of the system is done. Library QRPLxxxxx is cleared when the primary ASP of the ASP group is varied on.

Control language

87

Values allowed *YES *NO The system replaces the existing object with the new object being created that has the same name, library, and object type. The system does not replace the existing object that has the same name, library, and object type with the object being created.

JOBPTY, OUTPTY, and PTYLMT scheduling priority parameters: The scheduling priority parameters specify the priority values used by the system to determine the order in which the jobs and spooled files are selected for processing. Each job is given a scheduling priority that is used for both job selection and spooled file output. The job scheduling priority is specified by the JOBPTY parameter in commands like the Batch Job (BCHJOB), Submit Job (SBMJOB), Create Job Description (CRTJOBD), and Change Job Description (CHGJOBD) commands. The priority for producing the spooled output from a job is specified by the OUTPTY parameter in the same commands. In addition, because every job is processed under a specific user profile, the priority for jobs can be limited by the PTYLMT parameter specified on the Create User Profile (CRTUSRPRF) and Change User Profile (CHGUSRPRF) commands. This parameter value controls the maximum job scheduling priority and output priority that any job running under a user profile can have; that is, the priority specified in the JOBPTY and OUTPTY parameters of any job command cannot exceed the priority specified in the PTYLMT parameter for that user profile. The scheduling priority is used to determine the order in which jobs are selected for processing and is not related to the process priority specified in the class object. The three scheduling priority parameters specify the following: v The PTYLMT parameter specifies the highest scheduling priority for any job that you submit. In the commands that affect the user profile, the PTYLMT parameter specifies the highest priority that can be specified in another JOBPTY parameter on commands relating to each specific job. You can specify a lower priority for a job on the command used to submit the job. If you specify a higher priority for JOBPTY in the BCHJOB or SBMJOB command than is specified for PTYLMT in the associated user profile, an error message is shown on the display and the maximum priority specified in PTYLMT is assumed. If a higher job priority is specified in the CHGJOB or CHGJOBD command, an error message is shown and the attributes are not changed. v The JOBPTY parameter specifies the priority value to be used for a specific job being submitted. In the commands relating to a specific job being submitted, the JOBPTY parameter specifies the actual scheduling priority for the job. v The OUTPTY parameter specifies the priority for producing the output from all spooled output files from the job. The priority value specified in the OUTPTY parameter determines the order in which spooled files are handled for output. The same value is applied to all the spooled files produced by the job. The scheduling priority can have a value ranging from 0 through 9, where 1 is the highest priority and 9 is the lowest priority. Any job with a priority of 0 is scheduled for processing before all other jobs that are waiting and that have priorities of 1 through 9. The priority parameters can be specified on the following commands.
Table 12. Priority parameter Priority parameter JOBPTY Commands on which it can be specified ADDJOBJS, BCHJOB, CHGJOB, CHGJOBD, CHGJOBJS, CRTJOBD, SBMJOB, SBMJOBJS

88

System i: Programming Control language

Table 12. Priority parameter (continued) Priority parameter OUTPTY Commands on which it can be specified ADDJOBJS, BCHJOB, CHGDKTF, CHGJOBD, CHGJOBJS, CHGJOB, CHGJOBD, CHGJOBJS, CHGPJ, CHGPRTF, CHGSPLFA, CRTDKTF, CRTJOBD, CRTPRTF, OVRDKTF, OVRPRTF, SBMJOB, SBMJOBJS CHGUSRPRF, CRTUSRPRF, RTVUSRPRF

PTYLMT

Values allowed Depending upon the command, one or more of the following values apply to the parameter. 5 If a value is not specified in the CRTUSRPRF command, five is the default value that is assumed for the priority limit for the user profile. That would be the highest priority that the user could specify for any job he submits for processing. If not specified in the CRTJOBD command, five is the default value for both the job scheduling priority and the output priority. The priority assigned, or the highest priority that can be assigned, does not change. *JOBD The scheduling priority for the job is obtained from the job description under which the job runs. scheduling-priority: Specify a priority value ranging from 0 through 9, where 0 is the highest priority and 9 is the lowest priority. Priority 0 is allowed only on CHGJOB. SEV parameter: The severity (SEV) parameter specifies a severity code. The severity (SEV) parameter specifies the severity code that: v v v v Describes the level of severity associated with an error message. Indicates the minimum severity level that causes a message to be returned to a user or program. Causes a batch job to end. Causes processing of a command to end if a syntax error of sufficient severity occurs.

*SAME

Note: The LOG parameter on some commands also uses these severity codes for logging purposes (to control which job activity messages and error messages are logged in the job log). The severity code is a 2-digit number that can range from 00 through 99. The higher the value, the more severe or important the condition. The severity code of a message that is sent to a user indicates the severity of the condition described by the message. More than one message can have the same severity code. If a severity code is not specified for a predefined message, it is assumed to be 00 (information only). You can specify a severity code for any message when it is defined by the Add Message Description (ADDMSGD) command. To change the severity code of a message, use the Change Message Description (CHGMSGD) command. IBM -defined severity codes are used in all of the IBM -supplied messages that are shipped with the system. 00 - Information: A message of this severity is for information purposes only; no error was detected and no reply is needed. The message could indicate that a function is in progress or that it has reached a successful completion.
Control language

89

10 - Warning: A message of this severity indicates a potential error condition. The program may have taken a default, such as supplying missing input. The results of the operation are assumed to be what was intended. 20 - Error: An error has been detected, but it is one for which automatic recovery procedures probably were applied, and processing has continued. A default may have been taken to replace input that was in error. The results of the operation may not be valid. The function may be only partially complete; for example, some items in a list may be processed correctly while others may fail. 30 - Severe Error: The error detected is too severe for automatic recovery, and no defaults are possible. If the error was in source data, the entire input record was skipped. If the error occurred during program processing, it leads to an abnormal end of the program (severity 40). The results of the operation are not valid. 40 - Abnormal End of Program or Function: The operation has ended, possibly because it was unable to handle invalid data, or possibly because the user ended it. 50 - Abnormal End of Job: The job was ended or was not started. A routing step may have ended abnormally or failed to start, a job-level function may not have been performed as required, or the job may have been ended. 60 - System Status: A message of this severity is issued only to the system operator. It gives either the status of or a warning about a device, a subsystem, or the whole system. 70 - Device Integrity: A message of this severity is issued only to the system operator. It indicates that a device is malfunctioning or in some way is no longer operational. You may be able to restore system operation, or the assistance of a service representative may be required. 80 - System Alert: A message of this severity is issued only to the system operator. It warns of a condition that, although not severe enough to stop the system now, could become more severe unless preventive measures are taken. 90 - System Integrity: A message of this severity is issued only to the system operator. It describes a condition that renders either a subsystem or the whole system inoperative. 99 - Action: A message of this severity indicates that some manual action is required, such as specifying a reply or changing printer forms. Related tasks Assigning a severity code on page 460 The severity code you assign to a message on the Add Message Description (ADDMSGD) command indicates how important the message is. SPLNBR parameter: The spooled file number (SPLNBR) parameter is used when more than one spooled file is created by a job and the files all have the same name. The files are numbered, starting with 1, in the order that they are opened by the job. The job log is always the last file for a job.

90

System i: Programming Control language

A file number is generated for each file when it is opened within a job (when output records are produced) and it is used by the system as long as the job, the files, or both are on the system. If the files are not uniquely named because they were opened more than once, this file number is used to specify which file (or group of records, if the complete file has not yet been produced) is acted upon by a CL command. TEXT parameter: The TEXT parameter specifies the user-defined description that briefly describes the object that is being created or changed. The description can include up to 50 characters; if it is a quoted string (that is, enclosed in single quotation marks), any of the 256 EBCDIC characters can be used. The single quotation marks are not required if the string does not contain any blanks or other special characters. Any of the 50 character positions not filled by the specified description are padded with blanks. The description is used to describe any of the i5/OS objects when the named object is shown on the display by the Display Object Description (DSPOBJD) command. Only objects for which object operational authority has been obtained can be displayed by a user. For commands that use a database source file to create some type of object, you can (by default) use the text from the source file member as the text for the newly-created object. For example, if you use the Create Control Language Program (CRTCLPGM) command to create a CL program, but you do not specify a description in the TEXT parameter, the text specified for the source file member (SRCMBR parameter) of the source file (SRCFILE parameter) is assumed as the descriptive text for the CL program. Values allowed Depending upon the command, one or more of the following values apply to the TEXT parameter. *SRCMBRTXT For commands that create objects based on database source files only, the text is taken from the source member. If a device or an inline file is used for source input or if source is not used, the text is left blank. *BLANK The user description of the object being created or changed is left blank. *SAME The user-defined description does not change. description Specify the description of the object being created or changed. Up to 50 characters enclosed in single quotation marks (required for blanks and other special characters) can be specified to describe the object. If a single quotation mark is one of the 50 characters, two single quotation marks () must be used instead of one to represent the single quotation mark character. Related reference OBJTYPE parameter on page 83 The object type (OBJTYPE) parameter specifies the types of i5/OS objects that can be operated on by the command in which they are specified. VOL parameter: The volume (VOL) parameter specifies the volume identifiers of the volumes used in a tape or optical operation.

Control language

91

A tape volume consists of a tape cartridge or reel. An optical volume consists of a single side of an optical cartridge or a single CD-ROM. Optical cartridges are dual-sided and each side is a separate volume. The volume identifier is the identifier stored on each tape or optical disk (in the volume label area) that it identifies. An inquiry message is sent to the system operator if a volume identifier is missing or out of order. Tape volumes must be on the tape units in the same order as their identifiers are specified in the VOL parameter and as the device names are specified in the DEV parameter of the tape device file commands. However, if the tapes are read backward (a function supported in COBOL), the volumes must be in reverse order to that specified in the VOL parameter. Nevertheless, the device names are still specified in forward order in the DEV parameter. In general, the rule for specifying tape volume identifiers is that as many as 6 characters, containing any combination of letters and digits, can be used. Special characters can be used if the identifier is enclosed in single quotation marks. However, if the tape is used on an operating system other than the i5/OS operating system, the requirements for specifying identifiers must be considered. Optical volume identifiers can be up to 32 characters long and can contain any combination of digits and uppercase letters. Each optical volume identifier must be unique. No two optical volumes with the same identifier can be present on the system at the same time. For labeled tapes, the following rules apply: v Characters: A maximum of 6 characters, or fewer, can be specified for each volume identifier. Alphabetic and numeric characters can be used in any order. v Uniqueness: More than one volume can have the same identifier. You may have a file using the same identifier for several volumes; in this case, the system keeps track of the order internally with a sequence number written on the volumes. However, volume identifiers should be unique whenever possible. v Order: When multiple volumes (with different identifiers) are used in a single operation, they must be in the same order as the volume identifiers specified in the VOL parameter. Multivolume files If multiple volumes (tapes) are used in an operation and all have the same volume identifier, that identifier must be specified in the VOL parameter once for each volume used. For example, if three tapes named QGPL are used in a save operation, VOL(QGPL QGPL QGPL) must be specified. When a multivolume file on tape is processed and multiple tape units are used, the tape volumes must be placed in the tape devices in the same order as they are specified in the VOL parameter. For example, if five volumes and three tape units are used, they are mounted as follows: VOL1 on unit 1, VOL2 on unit 2, VOL3 on unit 3, VOL4 on unit 1, and VOL5 on unit 2. Values allowed *MOUNTED The volume currently placed in the device is used. *NONE No volume identifier is specified. *SAME Previously specified volume identification does not change. *SAVVOL The system, using the save/restore history information, determines which tape volumes contain

92

System i: Programming Control language

the most recently saved version. If the device specified in the DEV parameter of the restore command does not match the device of the most recently saved version of the object, an error message is returned to the user, and the function is ended. If the wrong volume is mounted in the unit specified by the command, a message is returned to the system operator that identifies the first volume that must be placed in the device before the restore operation can begin. volume-identifier Specify the identifiers of one or more volumes in the order in which they are put on the device and used. Each tape volume identifier contains a maximum of 6 alphanumeric characters. Each optical volume identifier contains a maximum of 32 characters. A blank is used as a separator character when listing multiple identifiers. Related information Optical device programming WAITFILE parameter: The WAITFILE parameter allows you to specify whether and how long a program waits for resources. You use the WAITFILE parameter to specify the maximum number of seconds that a program waits for the following: v File resources to be allocated when the file is opened v Session resources when the evoke function is issued for an APPC device v The device to be allocated when an acquire operation is performed to read the file If the program must wait, it will be placed in a wait state until the resources are available or until the wait time expires. If two or more file resources are needed and are not available because they are being used by different system users, the acquisition of each resource might require a wait. This maximum is applied to each wait. The length of the wait can be specified in this parameter, or the default wait time of the class that applies to the object can be used. If the file resources cannot be allocated in the specified number of seconds, an error message is returned to the program. The file resources that must be allocated depend on the type of file being opened. File resources consist of the following. v For device files that are not spooled (SPOOL(*NO)), the file resources include the file description and device description. Because the device description must be allocated, the device itself must also be available. v For device files that are spooled (SPOOL(*YES)), the file resources include the file description, the specified output queue, and storage in the system for the spooled data. Because the data is spooled, the device description (and thus the device itself) need not be available. v For database files, the file resources consist of the file and member data. The files associated member paths are not accessed, and therefore, the system does not wait for them. A file open exception error can occur before the WAITFILE time has expired when an access path is not available (for example, when the access path is being rebuilt). The Allocate Object (ALCOBJ) command can be used to allocate specific file resources before the file is opened. The session resources that were allocated for an APPC device conversation can be lost between the time the application issues a detach function or receives a detach indication and the time another evoke function is issued. If the session resource is lost, this parameter is used to determine the length of time that the system waits for another session resource.

Control language

93

Values allowed *IMMED The program does not wait; when the file is opened, an immediate allocation of the file resources is required. *CLS 1-32767 Specify the number of seconds that the program waits for the file resources to be allocated. The default wait time specified in the class description is used as the wait time for the file resources to be allocated.

Parameter values used for testing and debugging

The operating system includes functions that let a programmer observe operations performed as a program runs. Testing functions can be used to locate operations that are not performing as intended. These functions can be used in either batch or interactive jobs from a workstation. In either case, the program being observed must be in the testing environment, called debug mode. The testing functions narrow the search for errors that are difficult to find in the procedures source statements. Often, an error is apparent only because the output produced is not what is expected. To find those errors, you need to be able to stop the program at a given point (called a breakpoint) and examine variable information in the program to see if it is correct. You might want to make changes to those variables before letting the program continue running. You do not need to know machine language instructions, nor is there a need to include special instructions in the program to use the testing functions. The i5/OS testing functions let you: v Stop a running program at any named point in the programs source statements. v Display information about procedure variables at any point where the program can be stopped. You can also change the variable information before continuing procedure processing. This section contains expanded descriptions of the program variable, basing pointer, subscript, and qualified-name parameter values. These values can be specified on the Add Breakpoint (ADDBKP), Add Trace (ADDTRC), Change High-Level Language Pointer (CHGHLLPTR), Change Program Variable (CHGPGMVAR), and Display Program Variable (DSPPGMVAR) commands. See the appropriate Integrated Language Environment (ILE) guide for debugging information with other ILE languages. Related tasks Debugging ILE programs on page 349 To debug your Integrated Language Environment (ILE) programs, use the ILE source debugger. Debugging original program model programs on page 370 To debug your original program model (OPM) programs, use testing functions. These functions are available through a set of commands that can be used interactively or in a batch job. Program-variable description: The program variable must be enclosed in single quotation marks if it contains special characters. Up to 132 characters can be specified for a program variable name. This includes any subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing single quotation marks when special characters are used.
Program Variable .-------------------. V | >>-qualified-name---subscript------,subscript-------+----------><

94

System i: Programming Control language

Note: The maximum is 14 repetitions. Some examples follow:

COUNTA VAR1(2,3) A.VAR1(I,3,A.J,1) VAR1 OF A(I,3,J OF A) &LIBNAME

Basing-pointer description: The basing pointer must be enclosed in single quotation marks if it contains special characters. Up to 132 characters can be specified for a basing pointer name. This includes any subscripts, embedded blanks, parentheses, and commas. It does not include the enclosing single quotation marks when special characters are used.
Basing Pointer .-------------------. V | >>-qualified-name---subscript------,subscript-------+----------><

Note: The maximum is 14 repetitions. Some examples follow:

PTRVAR1 [Link](5,B.I)

If more than one basing pointer is specified for a variable, the list of basing pointers must be enclosed in parentheses. When multiple basing pointers are specified, they must be listed in order, from the first basing pointer to the last, when used to locate the variable. In the following example, the PTR_1 basing pointer is the first basing pointer used to locate the variable; it either must have a declared basing pointer, or it must not be a based variable. The address contained in the PTR_1 pointer is used to locate the A.PTR_2 pointer (which must be declared as a based pointer variable). The contents of the A.PTR_2 pointer are used to locate the PTR_3 pointer array (which must also be declared based), and the contents of the specified element in the last pointer array are used to locate the variable. An example is:
(PTR_1 A.PTR_2 PTR_3(1,B.J))

Subscript description: An integer number contains from 1 through 15 digits with an optional leading sign (either plus or minus). A decimal point is not allowed in an integer-number subscript. If a decimal point is specified, the subscript value is not interpreted as the correct numeric value by the system, and an error message is returned.
Subscript .-integer-number--. >>-+-qualified-name--+----------------------------------------->< -*---------------

An asterisk (*) can be used to request a single-dimensional cross-section display of an array program variable. An asterisk can only be specified for a subscript on the primary variable (not on a basing pointer) for the PGMVAR keyword on the Add Break Point (ADDBKP), Add Trace (ADDTRC), and Display Program Variable (DSPPGMVAR) commands. In addition, if the variable has multiple dimensions, only one of the subscript values can be an asterisk. An example of a request to display an array cross-section is as follows:
DSPPGMVAR PGMVAR(X1(*,5,4))

Control language

95

This display shows the values of all elements of the array that have the second subscript equal to five, and the third subscript equal to four. Qualified-name description: Some high-level languages might allow you to declare more than one variable with the same fully qualified name (although you generally are not able to refer to these variables in the high-level language program after they are declared). If you attempt to refer to such a variable using an i5/OS test facility command, the system selects one of the variables and uses it for the operation. No error is reported when a duplicate fully qualified name is selected.
Qualified-Name >>--+-/ODV-number------------------------------+--------------->< | .------------------------. | | V | | -variable-+----+-OF-+--variable-------+-+- | -IN- | | .---------------. | | V | | ---variable-------+----------

Note: The maximum is 19 repetitions. Rules for qualified name description v An ODV number is a slash (/) followed by 1 to 4 hexadecimal digits (0 through 9, and A through F). v The variable-name must be the name of a variable in the program. This name must be specified the same way in the high-level language. Some high-level languages introduce qualifier variable names in addition to the ones you specified in the source for your program. See the appropriate high-level language manual for more information about variable names. v Blanks must separate the variable-names from the special words OF and IN. v When a period is used to form a qualified name, no blanks can appear between it and the variable-names. The ordering of the variable names must follow these rules: - For qualified names that contain no embedded period, the variable names are assumed to be specified from the lowest to the highest levels in the structure. - For qualified names that contain one or more embedded periods, the variable names are assumed to be specified from the highest to the lowest levels in the structure. When an ODV number is not used for the qualified name, enough qualifier variable names must be specified so that a single unique variable can be identified in the program. Whether the qualified name is a simple name (only one variable name specified) or a name with multiple qualifier variable names, the variable in the program is uniquely identified if either of the following conditions is true (these conditions may require you to specify more qualifier variable names for i5/OS test facility commands than you need to specify in the high-level language program to uniquely select a program variable): - A variable is uniquely identified if there is one and only one variable in the program with a set of qualifier variables matching the qualified variable name specified. - A variable is uniquely identified in the program if it has exactly the same set of qualifier variables as the qualifier variable names specified. When the complete set of qualifiers is specified, the variable name is said to be fully qualified. A variable that is a fully qualified match for the qualified-name is selected even if there are other variables with names that match the qualified name but have additional qualifier variables which were not specified.

96

System i: Programming Control language

Control language elements

Control language (CL) contains elements such as character sets and values, expressions, built-in functions, and naming within commands.

CL character sets and values

The EBCDIC character sets, special characters, and IBM-defined fixed values called predefined values can be used in CL. Character sets: Control language (CL) uses the extended binary-coded decimal interchange code (EBCDIC) character set. For convenience in describing the relationship between characters used in the control language and those in the EBCDIC character set, the following control language categories contain the EBCDIC characters shown.
Category Alphabetic Numeric Alphanumeric
1,2 1

Characters included 26 letters (A through Z), $, #, and @ 10 digits (0-9) A through Z, 0 through 9, $, #, @, period (.), and underscore (__) All other EBCDIC characters

Special Characters Notes:

1. Lowercase letters (a through z) are accepted, but they are translated into the corresponding uppercase letters by the system except when they are included within a quoted character string or a comment, or they are specified for a value on a parameter that has the character (*CHAR) or the path name (*PNAME) attribute for its TYPE parameter and the mixed case (*MIXED) attribute for its CASE parameter in the command definition. 2. The underscore (__) is an alphanumeric connector that can be used in i5/OS CL to connect words or alphanumeric characters to form a name (for example, PAYLIB__01). This use of the underscore might not be valid in other high-level languages.

The first three categories contain the characters that are allowed in quoted and unquoted character strings, in comments, and in CL names, such as in names of commands, labels, keywords, variables, and i5/OS objects. Special characters in the last category can only be used in quoted character strings and comments; they cannot be used in unquoted strings. However, some have special syntactical uses when coded in the proper place in CL commands. Related concepts Special character use on page 98 Special characters can be used only in these special ways or inside quoted character strings or comments. Double-byte character text in CL commands: You can use double-byte character data anywhere in a CL command that descriptive text can be used. Enter double-byte character text as follows: 1. Begin the double-byte character text with a single quotation mark (). 2. Enter a shift-out character. 3. Enter the double-byte character text. 4. Enter a shift-in character. 5. End the double-byte character text with a single quotation mark ().

Control language

97

For example, to enter the double-byte character literal ABC, enter the following, where shift-out character and represents the shift-in character: ABC

represents the

Limit the length of a double-byte character text description of an object to 14 double-byte characters, plus the shift control characters, to make sure that the description is properly displayed and printed. Special character use: Special characters can be used only in these special ways or inside quoted character strings or comments. The special EBCDIC characters are used by the CL in various ways. They are most frequently used as delimiters and as symbolic operators in expressions. The special characters, as shown in the following table, have assigned meanings when coded in control language commands.
Table 13. Delimiters Name Single quotation mark Begin and end comment Blank Symbol /*
b 1

Meanings A single quotation mark delimiters indicate the beginning and end of a quoted character string (a constant).

*/

Indicates the beginning and end of a comment. Basic delimiter for separating parts of a command (label, command name, and its parameters), and for separating values inside lists. Ending delimiter for command labels. Separates parts of time values. 3 In many countries, used as decimal point in numeric values. Separates parts of date values. 2 Grouping delimiter for lists and parameter values, and for evaluating the order of expressions. Decimal point. Used to separate the name and extension of a document and folder name and to separate the parts of date values. 2

Colon Comma

: ,

Left and right parentheses ( ) Period .

Quote Slash Slashes

/ //

Start of a quoted object name. Connects parts of qualified names or path names. Identifying characters used in positions 1 and 2 of BCHJOB, ENDBCHJOB, and DATA commands in the job stream. Also, used as a default delimiter on inline data files.
b

Notes: 1. Because this character does not resolve in the online version of this book, only when the character cannot be clearly explained in another manner. 2. Valid only when the job date separator value specifies the same character. 3. Valid only when the job time separator value specifies the same character. is used to represent a blank space

Related concepts Character sets on page 97 Control language (CL) uses the extended binary-coded decimal interchange code (EBCDIC) character set. Symbolic operators on page 99 A variety of characters can be used as symbolic operators in CL commands.

98

System i: Programming Control language

Related reference Operators in expressions on page 104 Operators are used in expressions to indicate an action to be performed on the operands in the expression or the relationship between the operands. Symbolic operators: A variety of characters can be used as symbolic operators in CL commands. The following characters are used as symbolic operators in CL commands.
Table 14. Symbolic operators in CL commands Name And Asterisk Symbol & * Meanings Symbolic logical operator for AND. Multiplication operator. It indicates a generic name when it is the last character in the name. It indicates i5/OS reserved values (predefined parameter values and expression operators) when it is the first character in a string.
3

Concatenation Equal Greater than Less than Minus (hyphen) Not Or Plus Slash Notes:

|>, |<, and || = > < | + /

2 3

Character string operator (indicates both values are to be joined). Symbolic equal relational operator. Symbolic greater than relational operator. Symbolic less than relational operator. Subtraction operator, command continuation operator, and negative signed value indicator. Separates parts of date values. 1 Symbolic NOT relational operator. Symbolic logical operator for OR. Addition operator, command continuation character, and positive signed value indicator. Division operator. Separates parts of date values. 1 Used as the separator between parts of a qualified name.

1. Valid only when the job date separator value specifies the same character. 2. In some character sets, including the multinational character set, the character ^ replaces the character. Either ^ or *NOT can be used as the logical NOT operator in those character sets. 3. In some character sets, including the multinational character set, the character ! replaces the | character. Either ! or *OR can be used as the logical OR operator, and either || or *CAT can be used as the concatenation operator in those character sets.

Note: The symbolic operators can also be used in combinations. Symbolic operators can also be used in the following ways.
Table 15. Symbolic operators: Other uses Name Ampersand Percent Question mark Symbol & % ? Meanings It identifies a CL variable name when it is the first character in the string. It identifies a built-in system function when it is the first character in the string. It specifies a prompt request when it precedes a command name or keyword name.

Control language

99

Related concepts Special character use on page 98 Special characters can be used only in these special ways or inside quoted character strings or comments. Related reference Expressions on page 61 An expression is a group of constants or variables, separated by operators, that produces a single value. Operators in expressions on page 104 Operators are used in expressions to indicate an action to be performed on the operands in the expression or the relationship between the operands. Predefined values: Predefined values are IBM-defined fixed values that have predefined uses in control language (CL) and are considered to be reserved in the i5/OS operating system. Predefined values have an asterisk (*) as the first character in the value followed by a word or abbreviation, such as *ALL or *PGM. The purpose of the * in predefined values is to prevent possible conflicts with user-specified values, such as object names. Each predefined value has a specific use in one or more command parameters, and each is described in detail in the command description. Some predefined values are used as operators in expressions, such as *EQ and *AND. The predefined value *N is used to specify a null value and can be used to represent any optional parameter. A null value (*N) indicates a parameter position for which no value is being specified; it allows other parameters that follow it to be entered in positional form. To specify the characters *N as a character value (not as a null), the string must be enclosed in single quotation marks (*N) to be passed. Also, when the value *N appears in a CL program variable at the time it is run, it is always treated as a null value.

Expressions in CL commands
A character string expression can be used for any parameter, element, or qualifier that is defined with EXPR(*YES) in the command definition object. Any expression can be used as a single parameter in the Change Variable (CHGVAR) and If (IF) commands. An expression in its simple form is a single constant, a variable, or a built-in function. An expression typically contains two operands and an operator that indicates how the expression is to be evaluated. Two or more expressions can be combined to make a complex expression. The following types of expressions are supported in CL programs: v Arithmetic (&VAR + 15) v Character string (SIX || TEEN) v Relational (&VAR > 15) v Logical (&VAR & &TEST) A complex expression contains multiple operands, operators that indicate what operation is performed on the operands, and parentheses to group them. Only one operator is allowed between operands, except for the + and - signs when they immediately precede a decimal value (as a signed value), and the *NOT operator when it is used in a logical [Link] complex expression can have more than five nested levels of parentheses, including the outermost (required) level. Arithmetic and character string expressions can be used together in a complex expression if they are used with relational and logical operators; for example: (A=B&(1+2)=3). A pair of arithmetic expressions or a pair of character string expressions can be compared within a relational expression. Also, relational expressions can be used within a logical expression

100

System i: Programming Control language

Related reference Expressions on page 61 An expression is a group of constants or variables, separated by operators, that produces a single value. Arithmetic expressions: The operands in an arithmetic expression must be decimal constants, decimal, or integer CL variables. An arithmetic operator (only in symbolic form) must be between the operands. The results of all arithmetic expressions are decimal values, which may be stored in a CL variable. Note: The division operator (/) must be preceded by a blank if the operand that precedes it is a variable name. (For example, &A /2, not &A/2.) All other arithmetic operators may optionally be preceded or followed by a blank. Arithmetic operands can be signed or unsigned; that is, each operand (whether it is a numeric constant or a decimal or integer CL variable) can be immediately preceded by a plus (+) or minus (-) sign, but a sign is not required. When used as a sign, no blanks can occur between the + or - and its value. For example, a decimal constant of 23.7 can be expressed as +23.7 or -23.7 (signed) or as 23.7 (unsigned). The following are examples of arithmetic expressions:
(&A + 1) (&A + &B -15) (&A - &F) (&A+&B-15) (&A + (-&B))

If the last non-blank character on a line is a + or -, it is treated as a continuation character and not as an arithmetic operator. Character string expressions: The operands in a character string expression must be quoted or unquoted character strings, character variables, or the substring (%SUBSTRING or %SST) built-in function. The value associated with each variable or built-in function must be a character string. The result of concatenation is a character string. There are three operators that can be used in character string expressions. These operators concatenate (or join) two character strings, but each has a slightly different function. They are: *CAT (concatenation, symbol ||) operator The *CAT operator concatenates two character strings. For example: ABC *CAT DEF becomes ABCDEF Blanks are included in the concatenation. For example: ABC *CAT DEF becomes ABC DEF *BCAT (concatenation with blank insertion, symbol |>) operator The *BCAT operator truncates all trailing blanks in the first character string; one blank is inserted, then the two character strings are concatenated. Leading blanks on the second operand are not truncated. For example: ABC *BCAT DEF becomes ABC DEF ABC *BCAT DEF becomes ABC DEF *TCAT (concatenation with trailing blank truncation, symbol |<) operator The *TCAT operator truncates all trailing blanks in the first character string, then the two character strings are concatenated. All leading blanks on the second operand are not truncated. For example: ABC *TCAT DEF becomes ABCDEF ABC *TCAT DEF becomes ABCDEF ABC *TCAT DEF becomes ABC DEF ABC *TCAT DEF becomes ABC DEF
Control language

101

All blanks that surround the concatenation operator are ignored, but at least one blank must be on each side of the reserved value operator (*CAT, *BCAT, or *TCAT). If multiple blanks are wanted in the expression, a quoted character string (a character string enclosed within single quotation marks) must be used. Related reference Character string on page 56 A character string is a string of any EBCDIC characters (alphanumeric and special) that are used as a value. Example: Character string expressions: This example shows the variables and their corresponding character string expressions. Assume the following variables.
Variable &AA &BB &CC &DD Value GOOD REPLACEMENT ALSO GOOD METHOD

The following table shows character string expressions and the result.
Expression (&AA || &BB) (&AA||&BB) (&AA *CAT &BB) Result GOOD REPLACEMENT GOOD REPLACEMENT GOOD REPLACEMENT

(&CC |> &DD) (&CC *BCAT &DD)

ALSO GOOD METHOD ALSO GOOD METHOD

(A *CAT MOUSE) (A *CAT MOUSE)

AMOUSE A MOUSE

(FAST *CAT MOUSE) (FAST *BCAT MOUSE) (FAST *TCAT MOUSE)

FASTMOUSE FAST MOUSE FASTMOUSE

(AB *CAT CD) (AB *BCAT CD) (AB *TCAT CD)

ABCD AB CD ABCD

(%SST(&AA 1 5) *CAT (%SST(&BB 3 5))

GOOD PLACE

(%SST(&CC 1 9) *BCAT (%SST(&BB ALSO GOOD PLACE 3 5))

102

System i: Programming Control language

Expression (&AA *CAT TIME) (&CC *BCAT TIME)

Result GOOD TIME ALSO GOOD TIME

Example: Using character strings and variables: This example shows how several character variables and character strings can be concatenated to produce a message for a workstation operator. The example assumes that the variables &DAYS and &CUSNUM were declared as character variables, not decimal variables.
DCL CHGVAR VAR(&MSG)TYPE(*CHAR) LEN(100) * * &MSG (Customer *BCAT &CUSNAMD *BCATAccount Number *BCAT + &CUSNUM *BCAT is overdue by + *BCAT &DAYS *BCAT days.)

After the appropriate variables have been substituted, the resulting message might be:
Customer ABC COMPANY Account Number 12345 is overdue by 4 days.

If the variables &DAYS and &CUSNUM had been declared as decimal variables, two other CHGVAR commands would have to change the decimal variables to character variables before the concatenation could be performed. If, for example, two character variables named &DAYSALPH and &CUSNUMALPH were also declared in the program, the CHGVAR commands would be:
CHGVAR CHGVAR &DAYSALPH &CUSNUMALPH &DAYS &CUSNUM

Then instead of &DAYS and &CUSNUM, the new variables &DAYSALPH and &CUSNUMALPH would be specified in the CHGVAR command used to concatenate all the variables and character strings for &MSG. Relational expressions: The operands in a relational expression can be arithmetic or character string expressions. They can also be logical constants and logical variables. Only two operands can be used with each relational operator. The data type (arithmetic, character string, or logical) must be the same for the pair of operands. The result of a relational expression is a logical value 0 or 1. Refer to the table in Operators in expressions for the meanings of the relational operators, which can be specified by symbols (=, >, <, >=, <=, =, >, <) or their reserved values (*EQ, *GT, *LT, *GE, *LE, *NE, *NG, *NL). If an operation involves character fields of unequal length, the shorter field is extended by blanks added to the right. Arithmetic fields are compared algebraically; character fields are compared according to the EBCDIC collating sequence.

Control language

103

When logical fields are compared, a logical one (1) is greater than logical zero (0). Symbolically, this is (1 > 0). The following are examples of relational expressions:
(&X *GT 25) (&X > 25) (&X>25) (&NAME *EQ GSD) (&NAME *EQ &GSD) (&NAME *EQ GSD) (&BLANK *EQ )

Logical expressions: The operands in a logical expression consist of relational expressions, logical variables, or constants that are separated by logical operators. Two or more of these types of operands can be used in combinations, making up two or more expressions within expressions, up to the maximum of five nested levels of parentheses. The result of a logical expression is a 0 or 1 that can be used as part of another expression or saved in logical variables. The logical operators used to specify the relationship between the operands are *AND and *OR (as reserved values), and & and | (as symbols). The AND operator indicates that both operands (on either side of the operator) have to be a certain value to produce a particular result. The OR operator indicates that one or the other of its operands can determine the result. The logical operator *NOT (or ) is used to negate logical variables or logical constants. All *NOT operators are evaluated before the *AND or *OR operators are evaluated. All operands that follow *NOT operators are evaluated before the logical relationship between the operands is evaluated. The following are examples of logical expressions:
((&C *LT 1) *AND (&TIME *GT 1430)) (&C *LT 1 *AND &TIME *GT 1430) ((&C < 1) & (&TIME *GT 1430)) ((&C<1)&(&TIME>1430)) (&A *OR *NOT &B) (&TOWN *EQ CHICAGO *AND &ZIP *EQ 60605)

Two examples of logical expressions used in the IF command are:

IF &A CALL PROG1 IF (&A *OR &B) CALL PROG1

Operators in expressions: Operators are used in expressions to indicate an action to be performed on the operands in the expression or the relationship between the operands. There are four kinds of operators, one for each of the four types of expressions: v Arithmetic operators (+, -, *, /) v Character operator (||, |>, |<) v Logical operators (&, |, ) v Relational operators (=, >, <, >=, <=, =, >, <)

104

System i: Programming Control language

Each operator must be between the operands of the expression in which it is used; for example, (&A + 4). Operators can be specified as a predefined value (for example, *EQ) or as a symbol (for example, =). v All predefined value operators must have a blank on each side of the operator:
(&VAR *EQ 7)

v Except for the division operator (/), symbolic operators need no blanks on either side. For example, either (&VAR=7) or (&VAR = 7) is valid. Where the division operator follows a variable name, the division operator must be preceded by a blank. For example, (&VAR / 5) or (&VAR /5) is valid; (&VAR/5) is not valid. The following character combinations are the predefined values and symbols that represent the four kinds of operators; they should not be used in unquoted strings for any other purpose.
Table 16. Predefined values and symbols representing the four kinds of operators Predefined value Predefined symbol + * / *CAT *BCAT *TCAT *AND *OR *NOT *EQ *GT *LT *GE *LE *NE *NG *NL Notes: 1. In some national character sets and in the multinational character set, the character | (hexadecimal 4F) is replaced by the character ! (exclamation point). Either ! or *OR can be used as the OR operator and either || or *CAT, !> or *BCAT, and !< or *TCAT can be used for concatenation in those character sets. 2. In some national character sets and in the multinational character set, the character (hexadecimal 5F) is replaced by the character *. Either * or *NOT can be used as the NOT operator in those character sets. || |> |< & | = > < >= <= = > <
2 2 2 1 2 1 1

Meaning Addition Subtraction Multiplication Division Concatenation Blank insertion with concatenation Blank truncation with concatenation AND OR NOT Equal Greater than Less than Greater than or equal Less than or equal Not equal Not greater than Not less than

Type Arithmetic operator Arithmetic operator Arithmetic operator Arithmetic operator Character string operator Character string operator Character string operator Logical operator Logical operator Logical operator Relational operator Relational operator Relational operator Relational operator Relational operator Relational operator Relational operator Relational operator

Related concepts Special character use on page 98 Special characters can be used only in these special ways or inside quoted character strings or comments. Symbolic operators on page 99 A variety of characters can be used as symbolic operators in CL commands. Related tasks
Control language

105

Adding conditional breakpoints on page 378 To add a conditional breakpoint to a program that is being debugged, use the Add Breakpoint (ADDBKP) command to specify the statement and condition. Priority of operators when evaluating expressions: When multiple operators occur in an expression, the expression is evaluated in a specific order depending upon the operators in the expression. Parentheses can be used to change the order of expression evaluation. The following table shows the priority of all the operators used in expressions, including signed decimal values.
Table 17. Priority of operators Priority 1 2 3 4 5 6 7 Operators signed (+ and -) decimal values, *NOT, *,/ +, - (when used between two operands) *CAT, ||, *BCAT, |>, *TCAT, |< *GT, *LT, *EQ, *GE, *LE, *NE, *NG, *NL, >, <, =, >=, <=, =, >, < *AND, & *OR, |

A priority of 1 is the highest priority (signed values are evaluated first); a priority of 7 is the lowest priority (OR relationships are evaluated last). When operators with different priority levels appear in an expression, operations are performed according to priorities. When operators of the same priority appear in an expression, operations are performed from left to right within the expression. Parentheses can always be used to control the order in which operations are performed. The value of a parenthetical expression is determined from the innermost level to the outermost level, following the previous priorities stated within matching sets of parentheses.

Built-in functions for CL

Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions. CL provides the following built-in functions: v %ADDRESS v %BINARY v %OFFSET v %SUBSTRING v %SWITCH Related concepts Additional rules for unique names on page 124 Additional rules involve special characters (as an extra character) for object naming. Related reference %ADDRESS built-in function in a CL program or procedure on page 201 The address built-in function (%ADDRESS or %ADDR) can be used to change or test the memory address stored in a CL pointer variable and can only be used within a CL procedure.

106

System i: Programming Control language

%BINARY built-in function on page 202 The binary built-in function (%BINARY or %BIN) interprets the contents of a specified CL character variable as a signed binary integer. %OFFSET built-in function on page 204 The offset built-in function (%OFFSET or %OFS) can be used to store or change the offset portion of a CL pointer variable and can only be used within a CL procedure. %SUBSTRING built-in function on page 205 The substring built-in function (%SUBSTRING or%SST) produces a character string that is a subset of an existing character string and can only be used within a CL procedure. %SWITCH built-in function on page 207 The switch built-in function (%SWITCH) compares one or more of eight switches with the eight switch settings already established for the job and returns a logical value of 0 or 1.

Naming within commands

The type of name you specify in control language (CL) determines the characters you can use to specify a name. For certain types of names, there are restrictions on the use of certain characters to represent the name. Those types of names are *NAME, *SNAME, and *CNAME. Note: For a description of how to specify these names when you use command definitions to create commands, see the PARM (parameter) and ELEM (element) statements in Defining a command on page 265. The characters allowed for the *NAME, *SNAME, and *CNAME names and the rules you use to specify them are shown in the following table.
Table 18. Allowable characters for *NAME, *SNAME, and *CNAME Type of name *NAME
1

First character A-Z, $, #, @

Other characters A-Z, 0-9, $, #, @, _, . A-Z, 0-9, $, #, @, _ A-Z, 0-9, $, #, @ Any except blank, *, ?, , ", X00-X3F, and XFF

Min. length 1

Max. length 256

*SNAME

A-Z, $, #, @ A-Z, $, #, @
2

256

*CNAME

Quoted name

"3

256

Notes: 1. The system converts lowercase letters to uppercase letters. 2. Quotation marks can only be used for basic names (*NAME). 3. Both the first and last characters must be a quotation mark ().

Related concepts Object naming rules on page 118 These rules are used to name all i5/OS objects used in control language (CL) commands. The parameter summary table for each CL command shows whether a simple object name, a qualified name, or a generic name can be specified. Related reference
Control language

107

Command definition statements on page 258 Command definition allows system users to create additional commands to meet specific application needs. CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. Folder and document names: Folder and document names should describe the contents of the folder or document. Folder names must be unique and should be easy to type, as well as descriptive to a user. To find a particular folder on the system and change a document stored in it, you must either supply the folder name or select it from a list of names. Document names must be unique in the folder and should be easy to type, as well as descriptive. You should give careful consideration to the names you use to help you find the document later. The name you use for a folder or a document must follow these rules: v The name must be unique within a folder. v A document or folder name can be 1 to 12 characters long, including an optional extension. If no extension is included, a document or folder name can have a maximum of eight characters. If an extension is included, the extension must start with a period and can have up to three additional characters. An extension in the document name allows you to identify the document by using specific information that can help you do a selective listing of documents on your system.

v A document or folder name can include any single-byte EBCDIC character except for the following special characters that the system uses for other purposes.
Character Asterisk (*) Slash (/) Question mark (?) Special uses Multiplication operator, indicates generic names, and indicates i5/OS reserved values Division operator, delimiter within system values, and separates parts of qualified object names Initiates requests for system help

v When a folder is stored in another folder, both folder names are used, separated by a slash (/). That combination of names is called a folder path. For example, if a folder named FOLDR2 is stored in FOLDR1, the path for FOLDR2 is FOLDR1/FOLDR2. FOLDR1 is the first-level folder. FOLDR2 is the

108

System i: Programming Control language

next-level folder. The name of a single folder can be 1 to 12 characters long, including an optional extension. A folder path can contain a maximum of 63 characters. Folder names should not begin with Q because the system-supplied folder names begin with Q. The following are examples of permitted folder names and folder paths:
@LETTERS [Link] PAYROLL/[Link] #TAX1/[Link]/$1988/PAYROLL/[Link]

Notes: 1. In CL commands, folder path names must be enclosed in single quotation marks to prevent the system from processing them as qualified (library/object) names. If a single quotation mark is to be part of the name, it must be specified as two consecutive single quotation marks. 2. A number of CL commands act on either documents or folders, and some act on both. The abbreviation DLO (document library object) is used when referring to either a document or folder. 3. In CL commands, folder and document names must be enclosed in single quotation marks if they contain characters that are CL delimiters. 4. The system does not recognize graphic characters; it recognizes only code points and uses the following assumptions: v All folder and document names are encoded using single-byte EBCDIC code pages. Since code points hex 41 through FE represent graphic characters in those code pages, they are the only code points that can be used in folder and document names. v Code point hexadecimal 5C represents the asterisk (*); 61 represents the slash (/); and 6F represents the question mark (?). They cannot be used in folder and document names. v The code points for lowercase letters in English are converted to the code points for uppercase letters. Hexadecimal 81 through 89 are converted to C1 through C9; 91 through 99 are converted to D1 through D9; and A2 through A9 are converted to E2 through E9. In addition to the folder and document names previously described, folders and documents are internally classified in the system by their system object names. These are 10-character names derived from date/time stamps, and, while they are generally not known to the user, they may be specified on some CL commands by specifying *SYSOBJNAM for the folder or document name and by specifying the system object name in a separate parameter. Related concepts Object naming rules on page 118 These rules are used to name all i5/OS objects used in control language (CL) commands. The parameter summary table for each CL command shows whether a simple object name, a qualified name, or a generic name can be specified. Related information Local device configuration Create Device Desc (Display) (CRTDEVDSP) command

i5/OS objects
An i5/OS object is a named unit that exists (occupies space) in storage, and on which operations are performed by the operating system. i5/OS objects provide the means through which all data processing information is stored and processed by the i5/OS operating system. Objects are the basic units on which commands perform operations. For example, programs and files are objects. Through objects you can find, maintain, and process your data on the system. You need only to know what object and what function (command) you want to use; you do not need to know the storage address of your data to use it.
Control language

109

CL commands perform operations on the i5/OS objects. Several types of i5/OS objects are created and used in the control language. i5/OS objects have the following characteristics in common: v Objects have a set of descriptive attributes that are defined when the object is created. v Objects that have to be used by the system to perform a specific function must be specified in the CL command that performs that function. v Objects have a set of attributes that describe it and give the specific values assigned for those attributes. v Generally, objects are independent of all other objects. However, some objects must be created before other objects can be created; for example, a logical file cannot be created if the physical file it must be based on does not exist. v Objects must be created before other operations that use the object are performed. Descriptions of the create commands (those commands that begin with the letters CRT) give more information about the object types that they create. v Every i5/OS object that is used by the control language has a name. The object name specified in a CL command identifies which object is used by the operating system to perform the function of the command. v Objects have either a simple, qualified, or generic name. The system supports various unique types of objects. Some types identify objects common to many data processing systems, such as: v v v v v v v Files Programs Commands Libraries Queues Modules Service programs

Other object types are less familiar, such as: v User profiles v Job descriptions v Subsystem descriptions v Device descriptions Different object types have different operational characteristics. These differences make each object type unique. For example, because a file is an object that contains data, its operational characteristics differ from those of a program, which contains instructions. Each object has a name. The object name and the object type are used to identify an object. The object name is assigned by the user creating the object. The object type is determined by the command used to create the object. For example, if a program was created and given the name OEUPDT (for order entry update), the program could always be referred to by that name. The system uses the object name (OEUPDT) and object type (program) to locate the object and perform operations on it. Several objects can have the same name, but they must either be different object types or be stored in different libraries. The system maintains integrity by preventing the misuse of certain functions, depending on the object type. For example, the command CALL causes a program object to run. If you specified CALL and named a file, the command would fail unless there happened to be a program with the same name. Related concepts

110

System i: Programming Control language

Objects and libraries on page 390 Tasks and concepts specific to objects and libraries include performing functions on objects, creating libraries, and specifying object authority.

Library objects
A library is an object that is used to group related objects, and to find objects by name when they are used. Thus, a library is a directory to a group of objects. You can use libraries to group the objects into any meaningful collection. For example, you can group objects according to security requirements, backup requirements, or processing requirements. The amount of available disk storage limits the number of objects that a library can contain, and the number of libraries on the system. The object grouping performed by libraries is a logical grouping. When a library is created, you can specify into which user auxiliary storage pool (ASP) or independent auxiliary storage pool (independent disk pool) the library should be created. All objects created into the library are created into the same ASP as the library. Objects in a library are not necessarily physically adjacent to each other. The size of a library, or of any other object, is not restricted by the amount of adjacent space available in storage. The system finds the necessary storage for objects as they are stored in the system. Most types of objects are placed in a library when they are created. The AUT parameter on CRTLIB defines the public authority of the library. The CRTAUT parameter specifies the default authority for objects that are created into the library. If the command creating the object specifies *LIBCRTAUT for the AUT parameter, the objects public authority is the create authority that was specified for the library. You can move most object types from one library to another, but a single object cannot be in more than one library at the same time. When you move an object to a different library, the object is not moved in storage. You now locate the object through the new library. You can also rename and copy most object types from one library into another. A library name can be used to provide another level of identification to the name of an object. As described earlier, an object is identified by its name and its type. The name of the library further qualifies the object name. The combination of an object name and the library name is called the qualified name of the object. The qualified name tells the system the name of the object and the library it is in. The following figure shows two libraries and the qualified names of the objects in them.

Two objects with the same name and type can exist in different libraries. Two different objects with the same name cannot exist in the same library unless their object types differ. This design allows a program that refers to objects by name to work with different objects (objects with the same name but stored in different libraries) in successive runs of the program without changing the program itself. Also, a workstation user who is creating a new object does not need to be concerned about names used for objects in other libraries. For example, in the following figure, a new file named MONTHUPD (monthly update) could be added to the library OELIB, but not to the library ACCTLIB. The creation of the file into
Control language

111

ACCTLIB would fail because another object named MONTHUPD and of type file already exists in library ACCTLIB.

An object is identified within a library by the object name and type. Many CL commands apply only to a single object type, so the object type does not have to be explicitly identified. For those commands that apply to many object types, the object type must be explicitly identified. Objects that use the integrated file system are located in directories and can be found by using path names or object name patterns instead of searching libraries. You can also use these directories to locate objects. Related concepts Integrated file system Related tasks Using libraries on page 403 A library is an object used to group related objects and to find objects by name. Thus, a library is a directory to a group of objects. Related information Independent disk pool examples

External object types

Many types of external objects are stored in libraries. Some types of objects can only be stored in a specific library. For those object types, the library where the objects are created is shown in the Default user library column in Table 19 on page 113. Other types of objects allow a library name to be specified when the object is created. The default value for the library name qualifier on the CL commands that create those types of objects is the special value *CURLIB. The *CURLIB value causes the name of the current library to be used. The current library for a job or thread can be set as a user profile attribute or job attribute or by running the Change Current Library (CHGCURLIB) command. If there is no current library in effect when the object is created, library QGPL is used. The other types of objects, identified by N/A (not applicable) in the Default user library column, cannot be stored in libraries. With the exception of the Dump System Object (DMPSYSOBJ) command, you cannot specify the object type in the format shown in the hexadecimal format column with commands.

112

System i: Programming Control language

Table 19. Predefined values and default library locations for external i5/OS object types Value *ALRTBL *AUTL *BLKSF *BNDDIR *CFGL *CHRSF *CHTFMT *CLD *CLS *CMD *CNNL *COSD *CRG *CRQD *CSI *CSPMAP *CSPTBL *CTLD *DDIR *DEVD *DIR *DOC *DSTMF *DTAARA *DTADCT *DTAQ *EDTD *EXITRG *FCT *FIFO *FILE *FLR *FNTRSC *FNTTBL *FORMDF *FTR *GSS *IGCDCT Object type Alert table Authorization list Block special file Binding directory Configuration list Character special file Chart format C/400 locale description Class Command Connection list Class-of-service description Cluster resource group Change request description Communications side information Cross-system product map Cross-system product table Controller description Distributed file directory Device description Directory Document Distributed stream file Data area Data dictionary Data queue Edit description Exit registration Forms control table First-in-first-out special file File Folder Font resources Font mapping table Form definition Filter Graphics symbol set Double-byte character set (DBCS) conversion dictionary

Hexadecimal format Default user library 0E09 1B01 1E05 1937 1918 1E06 190D 190B 1904 1905 1701 1401 192C 0E0F 1935 1922 1923 1201 1F02 1001 0C01 190E 1F01 190A 1920 0A01 1908 1913 0E04 1E07 1901 1912 1926 192B 1928 0E0B 190C 0E06 *CURLIB QSYS N/A *CURLIB QSYS N/A *CURLIB *CURLIB *CURLIB *CURLIB QSYS QSYS QUSRSYS *CURLIB *CURLIB *CURLIB *CURLIB QSYS N/A QSYS N/A QDOC N/A *CURLIB library with same name as data dictionary *CURLIB QSYS QUSRSYS *CURLIB N/A *CURLIB QDOC *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB

Control language

113

Table 19. Predefined values and default library locations for external i5/OS object types (continued) Value *IGCSRT *IGCTBL *IMGCLG *IPXD *JOBD *JOBQ *JOBSCD *JRN *JRNRCV *LIB *LIND *LOCALE *MEDDFN *MENU *MGTCOL *MODD *MODULE *MSGF *MSGQ *M36 *M36CFG *NODGRP *NODL *NTBD *NWID Object type Double-byte character set (DBCS) sort table Double-byte character set (DBCS) font table Image Catalog Internetwork packet exchange description Job description Job queue Job schedule Journal Journal receiver Library Line description Locale Media definition Menu description Management collection Mode description Compiler unit Message file Message queue AS/400 Advanced 36 machine AS/400 Advanced 36 machine configuration Node group Node list NetBIOS description Network interface description Network server configuration Network server description Output queue Overlay Page definition Page segment Hexadecimal format Default user library 191A 1910 192E 191E 1903 0E01 0E0C 0901 0701 0401 1101 1921 191C 1916 192D 1501 0301 0E03 1902 1E04 1924 192A 0E0E 1914 1601 1939 1D01 0E02 1929 1936 1927 *CURLIB QSYS QUSRSYS QSYS *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB QSYS QSYS *CURLIB *CURLIB *CURLIB NA, or QPFRDATA if library specified using QYPSCSCA API QSYS *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB QSYS QSYS QUSRSYS QSYS *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB *CURLIB QSYS

*NWSCFG *NWSD *OUTQ *OVL *PAGDFN *PAGSEG *PDFMAP *PDG *PGM *PNLGRP *PRDAVL

Portable Document Format map 0E11 Print Descriptor Group Program Panel group definition Product availability 1930 0201 1915 1933

114

System i: Programming Control language

Table 19. Predefined values and default library locations for external i5/OS object types (continued) Value *PRDDFN *PRDLOD *PSFCFG *QMFORM *QMQRY *QRYDFN *RCT *SBSD *SCHIDX *SOCKET *SPADCT *SQLPKG *SQLUDT *SRVPGM *SSND *STMF *SVRSTG *SYMLNK *S36 *TBL *TIMZON *USRIDX *USRPRF *USRQ *USRSPC *VLDL *WSCST Object type Product definition Product load Print Services Facility configuration

Hexadecimal format Default user library 191B 191D 1925 1932 1931 1911 0E08 1909 0E07 1E03 1C01 0202 191F 0203 0E05 1E01 1917 1E02 1919 1906 192F 0E0A 0801 0A02 1934 0E10 1938 QSYS QSYS *CURLIB *CURLIB *CURLIB QGPL QGPL *CURLIB QGPL N/A QGPL *CURLIB *CURLIB *CURLIB QGPL N/A QUSRSYS N/A QGPL *CURLIB QSYS *CURLIB QSYS *CURLIB *CURLIB *CURLIB *CURLIB

Query management form Query management query Query definition Reference code translate table Subsystem description Search index Local socket Spelling aid dictionary Structured Query Language package User-defined SQL type Service program Session description Bytestream file Server storage space Symbolic link System/36 machine description Table Time zone description User index User profile User queue User space Validation list Workstation user customization object

Related concepts Object types and common attributes on page 390 Each type of object on the system has a unique purpose within the system, and each object type has a common set of attributes that describes the object. Related reference OBJTYPE parameter on page 83 The object type (OBJTYPE) parameter specifies the types of i5/OS objects that can be operated on by the command in which they are specified. Related information Change System Collector Attributes (QYPSCSCA, QypsChgSysCollectorAttributes) API

Control language

115

Simple and qualified object names

The name of a specific object that is located in a library can be specified as a simple name or as a qualified name. A simple object name is the name of the object only. A qualified object name is the name of the library where the object is stored followed by the name of the object. In a qualified object name, the library name is connected to the object name by a slash (/). Either the simple name or the qualified name of an object can be specified if the object exists in one of the libraries named in the jobs library list; the library qualifier is optional in this case. A qualified name must be specified if the named object is not in a library named in the library list. Note: Although a job name also has a qualified form, it is not a qualified object name because a job is not an i5/OS object. A job name is qualified by a user name and a job number, not by a library name. The following table shows how simple and qualified object names are formed.
Table 20. Simple and qualified object names Name type Simple object name Qualified object name Name syntax object-name library-name/object-name Example OBJA LIB1/OBJB

Related concepts CL command delimiters on page 41 Command delimiters are special characters or spaces that identify the beginning or end of a group of characters in a command. CL command definition parts on page 44 Command definition allows system users to create additional commands to meet specific application needs. These commands are similar to the system commands. Related reference CL command names on page 6 The command name identifies the function that will be performed by the program that is called when the command is run. Most command names consist of a combination of a verb (or action) followed by a noun or phrase that identifies the receiver of the action (or object being acted on): (command = verb + object acted on). Command definition statements on page 258 Command definition allows system users to create additional commands to meet specific application needs. JOB parameter on page 76 The JOB parameter specifies the name of the job to which the command is applied.

Generic object names

Generic object names can be used when referring to multiple objects with similar names. A generic object name can refer to more than one object. That is, a generic name contains one or more characters that are the first group of characters in the names of several objects; the system then searches for all the objects that have those characters at the beginning of their names and are in the libraries named in the library list. A generic name is identified by an asterisk (*) as the last character in the name. A quoted generic name consists of a generic name enclosed in quotation marks. Unlike quoted names, if there are no special characters between the quotation marks, the quotation marks are not removed. The generic name ABC* causes the system to search for objects whose name begins with ABC.

116

System i: Programming Control language

A generic name can also be qualified by a library name. If the generic name is qualified, the system will search only the specified library for objects whose names begin with that generic name. Note: A generic name also can be qualified by one or more directories if it is a path name. In a path name, letters can be specified before and after the asterisk (*). When you specify a generic name, the system performs the required function on all objects whose names begin with the specified series of characters. You must have the authority required to perform that function on every object the generic name identifies. If you do not have the required authority for an object, the function is not performed and a diagnostic message is issued for each instance that the attempted generic function failed. A completion message is issued for each object the generic function operates on successfully. You must view the online low-level messages to see the completion messages. After the entire generic function is completed, a completion message is issued that states that all objects were operated on successfully. If one or more objects cannot be successfully operated on, an escape message is issued. If an override is in effect for a specific device file, the single object name specified on the override, rather than the generic name, is used to perform the operation. You might not be able to use a generic name for delete, move, or rename commands if the library containing the objects is already locked. A search for generic object names requires a more restrictive lock on the library containing the objects than a search for full object names. The more restrictive lock is necessary to prevent another user from creating an object with the same name as the generic search string in the library while the delete, move, or rename command is running. You can circumvent this problem by using the full name of the objects instead of a generic name. Or you can end the job or subsystem that has a lock on the library. Note: Use the Work with Object Locks (WRKOBJLCK) command to determine which jobs or subsystems have a lock on the library. For some commands, a library qualifier can be specified with the generic name to limit the scope of the operation. For example, a Change Print File (CHGPRTF) command with FILE(LIB1/PRT*) performs the operation on printer files that begin with PRT in library LIB1 only; printer files in other libraries are not affected. The limitations associated with the various library qualifiers are as follows: v library-name: The operation is performed on generic object names only in the specified library. v *LIBL: The operation is performed on generic object names in the library list associated with the job that requested the generic operation. v *CURLIB: The operation is performed on generic object names in the current library. v *ALL: The operation is performed on generic object names in all libraries for which you are authorized. v *USRLIBL: The operation is performed on generic object names in the user part of the library list for the job. v *ALLUSR: The operation is performed on all nonsystem libraries (libraries that do not start with the letter Q), with some exceptions. Note: A different library name, of the form QUSRVxRxMx, can be created by the user for each release that IBM supports. VxRxMx is the version, release, and modification level of the library.
Table 21. Generic object name Name type Simple generic name Qualified generic name Quoted generic name Name syntax generic-name* library-name/generic-name* generic-name* Example OBJ* LIB1/OBJ* ABC*

Control language

117

Related concepts Integrated file system Generic library names Object naming rules These rules are used to name all i5/OS objects used in control language (CL) commands. The parameter summary table for each CL command shows whether a simple object name, a qualified name, or a generic name can be specified. Generic names (*GENERIC) on page 120 A generic name is one that contains at least one initial character that is common to a group of objects, followed by an asterisk.

Object naming rules

These rules are used to name all i5/OS objects used in control language (CL) commands. The parameter summary table for each CL command shows whether a simple object name, a qualified name, or a generic name can be specified. Naming a Single Object In the name of a single object, each part (the simple name and the library qualifier name) can have a maximum of 10 characters. Naming a User-Created Object To distinguish a user-created object from an IBM-supplied object, you should not begin user-created object names with Q because the names of all IBM-supplied objects (except commands) begin with Q. Although you can use as many as 10 characters in CL object names, you might need to use fewer characters to be consistent with the naming rules of the particular high-level language that you are also using. Also, the high-level language might not allow underscores in the naming rules. For example, RPG limits file names to eight characters and does not allow underscores. Naming a Generic Object In a generic name, a maximum of nine alphanumeric characters can be used, not including the asterisk (*) that must immediately follow the last character. INV and INV* are valid values where a generic name is accepted. When the name INV is specified, only the object INV is referenced. When the generic name INV* is specified, objects that begin with INV are referred to, such as INV, INVOICE, INVENTORY, and INVENPGM1. When the quoted generic name INV* is specified, objects that begin with INV are referred to, such as INV%1 and INV>. Object Library Qualifier Limitations No library qualifier can be specified with the object name if the object being created is a library, user profile, line description, controller description, device description, mode description, class-of-service description, or configuration list. A library name can never be qualified because a library cannot be placed in a library. The other object types (*USRPRF, *LIND, *CTLD, *DEVD, *MODD, *COSD, and *CFGL) appear to be types that exist only in the QSYS library. When only the name of an object of these object types is accepted, a library qualifier cannot be specified with the object name. On the Display Object Description (DSPOBJD) command, where any object name is accepted, QSYS can be specified. Library List Qualifiers The predefined value *LIBL (and others, such as *CURLIB) can be used in place of a library name in most commands. *LIBL indicates that the libraries named in the jobs library list are used to find the object named in the second part of the qualified name. Duplicate Object Names Duplicate names are not allowed for objects of the same type in the same library. Two objects with the same name cannot be stored in the same library unless their object types are different. Two objects named OBJA can be stored in the library LIBx only if, for example, one of

118

System i: Programming Control language

the objects is a program and the other is a file. The following combinations of names and object types could all exist on the system at the same time.

If more than one library contains an object with the same name (and both libraries are in the same library list) and a library qualifier is not specified with the object name, the first object found by that name is used. Therefore, when you have multiple objects with the same name, you should specify the library name with the object name or ensure that the appropriate library occurs first in the library list. For example, if you are testing and debugging and choose not to qualify the names, ensure that your test library precedes your production library in the library list.

Default libraries
In a qualified object name, the library name is typically optional. If an optional library qualifier is not specified, the default given in the commands description is used (typically either *CURLIB or *LIBL). If the named object is being created, the current library is the default; when the object is created, it is placed either in the current library or in the QGPL (the general purpose library ) if no current library is defined. For objects that already exist, *LIBL is the default for most commands, and the jobs library list is used to find the named object. The system searches all of the libraries currently in the library list until it finds the object name specified. Related concepts Naming within commands on page 107 The type of name you specify in control language (CL) determines the characters you can use to specify a name. Generic object names on page 116 Generic object names can be used when referring to multiple objects with similar names. Folder and document names on page 108 Folder and document names should describe the contents of the folder or document. Related reference CL command names on page 6 The command name identifies the function that will be performed by the program that is called when the command is run. Most command names consist of a combination of a verb (or action) followed by a noun or phrase that identifies the receiver of the action (or object being acted on): (command = verb + object acted on).

Control language

119

Communication names (*CNAME): A communications name has a restrictive name syntax. It is typically used to refer to a device configuration object whose name length and valid character set is limited by one or more communication architectures. Communications names are the same as unquoted basic names with some exceptions: 1. Periods (.) and underscores (_) cannot be used. 2. For IBM commands, *CNAME is limited to 8 characters. An example of a communications name is shown as follows:
APPN3@@

Because restricted character sets are sometimes used by other IBM systems, use caution when choosing names that use the special characters #, $, and @. These special characters might not be on the remote systems keyboard. The names that can be exchanged with the remote systems include the following names: v Network IDS v Location names v Mode names v Class-of-service names v Control point names Related concepts Names (*NAME) When you create basic names and basic names in quoted form, follow these rules. Related reference CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. Generic names (*GENERIC): A generic name is one that contains at least one initial character that is common to a group of objects, followed by an asterisk. The asterisk identifies the series of common characters as a generic name; otherwise, the system interprets the series of characters as the name of a specific object. Related concepts Generic object names on page 116 Generic object names can be used when referring to multiple objects with similar names. Names (*NAME): When you create basic names and basic names in quoted form, follow these rules. *NAME (basic name in unquoted form) Every basic name can begin with the characters A-Z, $, #, or @ and can be followed by up to nine characters. The remaining characters can include the same characters as the first but can also include numbers 0-9, underscores (_), and periods (.). Lowercase letters are changed to uppercase letters by the system. Basic names used in IBM-supplied commands can be no longer than 10 characters. However, in

120

System i: Programming Control language

your own commands, you can define parameters of type *NAME (specified on the TYPE parameter of the PARM or ELEM statements) with up to 256 characters. Examples of basic names are shown as follows:
[email protected]# ONE_NAME LIB_0690 $LIBX

Names can be entered in quoted or unquoted form. If you use the quoted form, the following rules and considerations also apply: *NAME (basic name in quoted form) Every quoted name must begin and end with a quotation mark (). The middle characters of a quoted name can contain any character except , *, ?, , , hex 00 through 3F, or hex FF, and is delimited by a slash. Quoted names allow you to use graphic characters in the name. The quoted form of basic names used in IBM-supplied commands can be no longer than 8 characters (not including the quotation marks). In your own commands, you can define parameters of type *NAME in quoted form with up to 254 characters (not including the quotation marks). Note: Only basic names can be used in quoted form. Examples of quoted names are shown as follows:
"A" "AA%abc" "ABC%%abc"

When you use quoted names, you should be aware of certain restrictions: v Code points in a name might not be addressable from all keyboards. v Characters in a quoted name might not be valid in a high-level language. v The System/38 environment supports only simple (*SNAME) names. If other characters are used, the objects cannot be accessed as System/38 environment objects. v Names that are longer than eight characters cannot be accessed by the System/36 environment unless control language overrides are used. v A Structured Query Language (SQL) name that contains a period must be specified in an SQL statement in quotation marks. If a name enclosed in quotation marks is a valid unquoted basic name, the quotation marks are removed. Thus, ABC is equivalent to ABC. Because the quotation marks are removed, they are not included in the length of the name. ABCDEFGHIJ is, therefore, a valid name on IBM* commands even though it is longer than 10 characters. Related concepts Communication names (*CNAME) on page 120 A communications name has a restrictive name syntax. It is typically used to refer to a device configuration object whose name length and valid character set is limited by one or more communication architectures. Simple names (*SNAME) on page 123 Simple names are used for control language (CL) variables, labels, and keywords to simplify the syntax of CL. Simple names are the same as unquoted basic names but with one exception: periods (.) cannot be used. Related reference CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. Path names (*PNAME):
Control language

121

A path name is a character string that can be used to locate objects in the integrated file system. The string can consist of one or more elements, each separated by a slash (/). Each element is typically a directory or equivalent, except for the last element, which can be a directory, another object such as a file, or a generic presentation of an object or objects to be located. | Note: Some CL commands also allow the backslash (\) to be used as a separator by automatically converting the backslash (\) to a slash (/). Some other CL commands, however, treat the backslash | (\) no differently than any other character. Therefore, the backslash (\) separator should be used | with caution. | The / and \ characters and nulls cannot be used in the individual components of the path name when the / and \ characters are used as separators. The name can or cannot be changed to uppercase, depending on whether the file system containing the object is case-sensitive and whether the object is being created or searched for. If the parameter is defined as CASE(*MONO) (the default), any values that are not enclosed in single quotation marks will be changed to uppercase by the command analyzer. A separator character (for example, /) at the beginning of a path name means that the path begins at the top most directory, the root (/) directory. If the path name does not begin with a separator character, the path is assumed to begin at the current directory of the user entering the command. The path name must be represented in the CCSID currently in effect for the job. If the CCSID of the job is 65535, the path name must be represented in the default CCSID of the job. Hard-coded path names in programs are encoded in CCSID 37. Therefore, the path name should be converted to the job CCSID before being passed to the command. The maximum length of the path name character string on the CL commands is 5000 characters. When operating on objects in the [Link] file system, the component names must be of the form [Link]-type; for example:
/[Link]/[Link]/[Link]

If the objects are in an independent ASP [Link] file system, the name must be of the form:
/asp-name/[Link]/[Link]/[Link]

where asp-name is the name of the independent ASP. Path names must be enclosed in single quotation marks () when entered on a command line if they contain special characters. These marks are optional when path names are entered on displays. If the path name includes any quoted strings or special characters; however, the enclosing marks must be included. The following are rules for using special characters: v A tilde (~) character followed by a separator character (for example, /) at the beginning of a path name means that the path begins at the home directory of the user entering the command. v A tilde (~) character followed by a user name and then a separator character (for example, /) at the beginning of a path name means that the path begins at the home directory of the user identified by the user name. v In some commands, an asterisk (*) or a question mark (?) can be used in the last component of a path name to search for patterns of names. The * tells the system to search for names that have any number of characters in the position of the * character. The ? tells the system to search for names that have a single character in the position of the ? character. v To avoid confusion with i5/OS special values, path names cannot start with a single asterisk (*) character. To perform a pattern match at the beginning of a path name, use two asterisks (**). Note: This only applies to relative path names where there are no other characters before the asterisk.

122

System i: Programming Control language

v The path name must be enclosed in single quotation marks () and quotation marks () if any of the following characters are used in a component name: Asterisk (*) Note: To avoid confusion with i5/OS special values, do not start path names with a single asterisk (*) character. Question mark (?) Single quotation mark () Quotation mark () Tilde (~), if used as the first character in the first component name of the path name (if used in any other position, the tilde is interpreted as just another character)

Note: Using the previous characters as the first character in the first component name of the path name is not recommended because the meaning of the character in a command string could be confused and it is more likely that the command string will be entered incorrectly. v Do not use a colon (:) in path names. It has a special meaning within the system. v The processing support for commands and associated user displays does not recognize code points below hexadecimal 40 as characters that can be used in command strings or on displays. If these code points are used, they must be entered as a hexadecimal representation, such as the following example:
crtdir dir(X02)

Therefore, use of code points below hexadecimal 40 in path names is not recommended. This restriction applies only to commands and associated displays, not to APIs. In addition, a value of hexadecimal 00 is not allowed in path names. Related tasks Specifying the device name Accessing the integrated file system Related reference OBJ parameter on page 83 The object (OBJ) parameter specifies the names of one or more objects affected by the command in which this parameter is used. CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. Simple names (*SNAME): Simple names are used for control language (CL) variables, labels, and keywords to simplify the syntax of CL. Simple names are the same as unquoted basic names but with one exception: periods (.) cannot be used. Some examples of simple names are as follows:
NEWCMD LIB_2

Related concepts Names (*NAME) on page 120 When you create basic names and basic names in quoted form, follow these rules. Related reference CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes.
Control language

123

Additional rules for unique names: Additional rules involve special characters (as an extra character) for object naming. v A command label must be immediately followed by a colon (:). Blanks can follow the colon, but none can precede it. A command label name cannot be a quoted name. v A CL variable name must be preceded by an ampersand (&) to indicate that it is a CL variable used in a CL program. v The built-in functions for CL must be preceded by a percent sign (%) to indicate that it is an IBM-supplied built-in function that can be used in an expression. A built-in function name cannot be a quoted name. These special characters are not part of the name; each is an additional character attached to a name (making a maximum of 11 characters) indicating to the system what the name identifies. The names of i5/OS objects, CL program variables, system values, and built-in functions can be specified in the parameters of individual commands. Instead of specifying a constant value, a CL variable name can be used on most parameters in CL programs to specify a value that can change during the running of programs. It is the contents of the variable that identify the objects and variables that are used when the command is run. Related reference CL command label on page 40 Command labels identify particular commands for branching purposes in a CL program. Labels can also be used to identify statements in CL programs that are being debugged. They can identify statements used either as breakpoints or as starting and ending statements for tracing purposes. Variable name on page 60 A variable contains a data value that can be changed when a program is run. A variable name is the name of the variable that contains the value. Built-in functions for CL on page 106 Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions.

Database files and device files used by CL commands

Many of the IBM-supplied CL commands use database files and device files during processing. All of the commands and files for all licensed programs that meet the criteria are included: v The types of files included are: Database files: physical (PF) and logical (LF), including files with data and files used as model files (no data) Device files: tape (TAPF) and printer (PRTF) v The files are included only if a user might have a reason to use them, such as declaring them in a program so they can be overridden with another file. Two examples: You want to change some attributes for a printer device file, such as the font to be used or the printed lines per inch (the FONT or LPI parameter). You want to override the IBM-supplied file with your own output file (when valid). The types of files not included in this section are: v i5/OS-provided display (DSPF) device files, because they should not be changed or overridden. v Most of the i5/OS-provided database files used by directory commands, document library object commands, and optical index database files, because they cannot be overridden. As mentioned, IBM-supplied physical (PF) or logical (LF) files that are used as model files for certain commands are included in the following table. (Examples are the model files listed under the DSPFD,

124

System i: Programming Control language

DSPJRN, and STRPFRMON commands.) In most cases, these model files do not contain data; instead, they contain the definitions (or record formats) of the files to be created for storing the actual output data resulting from use of these commands. For the record formats of these files, you can display the files description online or you can refer to the topic collection that documents that command. Additionally, some files considered to be IBM-supplied files do not actually exist on the system until some function is used that requires the file and so creates it at that time. The following notes describe how the table of commands and files are sorted and explain the meanings of the superscripts used in Table 22. Notes: 1. The first column of the table lists the CL commands that use the i5/OS-provided files shown in the third column. The table entries are in alphabetic order by command name first. If there is more than one library for a command, they are further ordered by the file library name and then by file name within each library. 2. A superscript 1 ( 1) following the description of a file indicates that the file is used only when the output from the command is directed to that form of output-by an output-related parameter on the command. v The superscript 1 is used at the end of printer file (PRTF) descriptions to show that use of the printer file is dependent on the job environment and the print-related value specified (or assumed) on the command. For commands with an OUTPUT parameter (primarily DSPxxx and WRKxxx commands), the output is printed either when OUTPUT(*) is specified in a batch job, or when OUTPUT(*PRINT) is specified in a batch or interactive job. For other commands, the output is printed if a *PRINT, *LIST, or *SRC value is specified on a different parameter. v The superscript 1 is used at the end of database file (PF or LF) descriptions to show that use of the database file is dependent on the print-related value specified (or assumed) on the command. For commands with an OUTPUT parameter (primarily DSPxxx and SAVxxx commands), the output is directed to the database file when OUTPUT(*OUTFILE) is specified. The same is true for other commands that specify a value similar to *OUTFILE on one of its parameters. 3. A superscript 2 ( 2) following a files description indicates that the file is a model file and not an output file. As a model file, it defines the record format of the file created to contain the actual output. 4. Those files showing user-lib as the file library do not exist on the system until the user creates them. When the command is used, the file is created in the users specified library with the file name shown.
Table 22. Files used by CL commands (part 1) Command name ADDDOCCVN File library QUSRSYS QUSRSYS QUSRSYS ADDDSTQ ADDDSTRTE QUSRSYS QUSRSYS QUSRSYS ADDDSTSYSN ADDNETJOBE QUSRSYS QUSRSYS File name QAO1CRL QAO1CVNP QAO1DCVN QASNADSQ QASNADSQ QASNADSR QASNADSA QANFNJE File type LF PF PRTF PF PF PF PF PF File usage Document conversion logical file for input or output. Document conversion physical file for input or output. Document conversion printer file. SNADS distribution queues table. SNADS distribution queues table. SNADS routing table. SNADS secondary node ID table. Network job entry database file.
Control language

125

Table 22. Files used by CL commands (part 1) (continued) Command name ADDSOCE ADDTAPCTG File library QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS ADDTCPHTE ADDTCPIFC ADDTCPPORT ADDTCPRSI ADDTCPRTE ANSQST ANZACCGRP QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QSYS QPFR QPFR QPFR File name QAALSOC QATAMID QLTAMID QATACGY QLTACGY QATOCHOST QATOCIFC QATOCPORT QATOCRSI QATOCRTE QPQAPRT QAPTDDS QAPTPAGD QPPTPAG File type PF PF LF PF LF PF PF PF PF PF PRTF PF PF PRTF File usage Sphere of control file. Cartridge ID db file. Cartridge ID logical file. Category db file. Category logical file. TCP/IP host file. TCP/IP configuration file. TCP/IP configuration file. TCP/IP configuration file. TCP/IP configuration file. Q & A printer file. Performance data DDS source file. Performance database input file of files and programs in a process access group (PAG). Printer file of PAG data containing environment, job, file, and program summary data. Performance data collection file: analyze application database files data. Performance data DDS source file. Performance printer file showing physical-to-logical and logical-to-physical database file relationships. Performance input file of analyze application database files data showing logical file key structures. Performance data DDS source file. Performance printer file containing logical file key structure data. Performance printer file containing access path and record selection data. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, CIOP, CONF, DIOP, DISK, ECL, ETH, HDLC, IDLC, JOBS, LAPD, LIOP, MIOP, POOL, SYS, and X25. 2 Performance printer file containing the advisor report. 1 Performance data collection file: analyze application programs data. Performance printer file showing program-to-file and file-to-program relationships. Model output file for apply journaled changes.

ANZDBF

QPFR QPFR QPFR

QAPTAZDR QAPTDDS QPPTANZD

PF PF PRTF

ANZDBFKEY

QPFR

QAPTAZDR

PF

QPFR QPFR QPFR ANZPFRDTA QSYS

QAPTDDS QPPTANKM QPPTANZK QAPMxxxx

PF PRTF PRTF PF

QPFR ANZPGM QPFR QPFR

QPAVPRT QAPTAZPD QPPTANZP

PRTF PF PRTF

APYJRNCHG

QSYS

QAJRNCHG

PF

126

System i: Programming Control language

Table 22. Files used by CL commands (part 1) (continued) Command name APYJRNCHGX ASKQST CFGDSTSRV File library QSYS QSYS QUSRSYS QUSRSYS QUSRSYS CFGTCP QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS CFGTCPSMTP QUSRSYS QUSRSYS CHGDOCCVN CHGDTA QUSRSYS QIDU QIDU QSYS QSYS CHGDSTQ CHGDSTRTE QUSRSYS QUSRSYS QUSRSYS CHGFTPA CHGHTTPA CHGLPDA CHGPOPA CHGPRB QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS CHGQSTDB CHGSMTPA CHGTAPCTG QSYS QUSRSYS QUSRSYS QUSRSYS CHGTCPA CHGTCPHTE CHGTCPIFC CHGTCPRTE CHGTELNA CHKTAP QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QSYS File name QAJRNCHG QPQAPRT QASNADSA QASNADSQ QASNADSR QATOCHOST QATOCIFC QATOCPORT QATOCPS QATOCRSI QATOCRTE QATOCTCPIP QATMSMTP QATMSMTPA QAO1CRL QDTALOG QDTAPRT QPDZDTALOG QPDZDTAPRT QASNADSQ QASNADSQ QASNADSR QATMFTP QATMHTTP QATMLPD QATMPOPA QASXNOTE QASXPROB QPQAPRT QATMSMTP QATAMID QATAMID QATOCTCPIP QATOCHOST QATOCIFC QATOCRTE QATMTELN QSYSTAPE File type PF PRTF PF PF PF PF PF PF PF PF PF PF PF PF LF PRTF PRTF PRTF PRTF PF PF PF PF PF PF PF PF PF PRTF PF PF LF PF PF PF PF PF TAPF File usage Model output file for apply journaled changes extend. Q & A printer file. SNADS secondary node ID table. SNADS destination queues table. SNADS destination systems routing table. TCP/IP hostname file. TCP/IP interface file. TCP/IP port restrictions file. TCP/IP services file. TCP/IP RSI file. TCP/IP route file. TCP/IP attributes file. TCP/IP SMTP file. TCP/IP SMTP file. Document conversion logical file for input or output. Audit control log printer file. Record and accumulator total printer file. DFU runtime audit log. DFU runtime printer data file. SNADS distribution queues table. SNADS distribution queues table. SNADS routing table. TCP/IP FTP configuration file. TCP/IP HTTP file. TCP/IP LPD configuration file. POP server configuration file. Problem log user notes file. Problem log problem file. Q & A printer file. TCP/IP SMTP configuration file. Cartridge ID database file. Cartridge ID logical database file. TCP/IP attributes file. TCP/IP host file. TCP/IP interface file. TCP/IP routes file. TCP/IP TELNET configuration file. Printer file for tape output.
Control language

127

Table 22. Files used by CL commands (part 1) (continued) Command name CMPJRNIMG CPYF CPYFRMDKT CPYFRMQRYF CPYFRMTAP File library QSYS QSYS QSYS QSYS QSYS QSYS CPYPFRDTA QSYS File name QPCMPIMG QSYSPRT QSYSPRT QSYSPRT QSYSPRT QSYSTAP QAPMxxxx File type PRTF PRTF PRTF PRTF PRTF TAPF PF File usage Compare journal images printer file. Copy file printer file. Copy file printer file. Copy file printer file. Copy file printer file.
1 1 1 1

Tape device file used for input and output. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, BUS, CIOP, CONF, DIOP, DISK, DMPT, ECL, ETH, HDLC, IOBS, JOBS, LIOP, MIOP, POOL, RESP, RWS, SBSD, SYS, TSK, and X25. 2 Tape device file used for input and output. Copy file printer file.
1

QSYS CPYSRCF QSYS QSYS CRTBNDC CRTBNDCBL QGPL QGPL QSYS CRTBNDCL QGPL QSYS CRTBNDRPG QGPL QSYS CRTCBLMOD QGPL QSYS CRTCBLPGM QGPL QSYS CRTCLD QGPL QSYS CRTCLMOD QGPL QSYS CRTCLPGM QGPL QSYS CRTCMD QGPL QSYS CRTCMOD QGPL QSYS CRTDSPF QGPL QSYS CRTICFF QGPL

QSYSTAP QSYSPRT QSYSTAP QCSRC QCBLLESRC QSYSPRT QCLSRC QSYSPRT QRPGLESRC QSYSPRT QCBLLESRC QSYSPRT QLBLSRC QSYSPRT QCLDSRC QSYSPRT QCLSRC QSYSPRT QCLSRC QSYSPRT QCMDSRC QSYSPRT QCSRC QSYSPRT QDDSSRC QPDDSSRC QDDSSRC

TAPF PRTF TAPF PF PF PF PF PRTF PF PRTF PF PF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF

Tape device file used for output. ILE C source default input file. ILE COBOL source default input file. ILE COBOL source listing printer file. CL source default input file. CL source listing printer file.
1

ILE RPG source default input file ILE RPG source listing printer file. ILE COBOL source default input file. ILE COBOL source listing printer file. OPM COBOL source default input file. OPM COBOL source listing printer file.
1

C locale description default source input file. C locale description source listing printer file. 1 CL source default input file. CL source listing printer file. CL source default input file. CL source listing printer file.
1 1

Command definition source default input file. Command definition source listing printer file. ILE C source default input file. ILE C source listing printer file. DDS source default input file. DDS source listing printer file. DDS source default input file.
1 1

128

System i: Programming Control language

Table 22. Files used by CL commands (part 1) (continued) Command name File library QSYS CRTLF QGPL QSYS CRTMNU QGPL QSYS CRTMSGFMNU QGPL QGPL QSSP QSYS CRTPF QGPL QSYS CRTPGM CRTPNLGRP QSYS QGPL QSYS CRTPRTF QGPL QSYS CRTQSTDB QSYS QSYS CRTQSTLOD CRTRJEBSCF CRTRJECFG CRTRJECMNF CRTRPGMOD QSYS QRJE QRJE QRJE QGPL QSYS CRTRPGPGM QGPL QSYS CRTRPTPGM QGPL QSYS CRTSQLC QGPL QSYS CRTSQLCI QGPL QSYS CRTSQLCBL QGPL QSYS CRTSQLCBLI QGPL QSYS CRTSQLFTN QGPL QSYS File name QPDDSSRC QDDSSRC QPDDSSRC QMNUSRC QSYSPRT QDDSSRC QS36DDSSRC QPUTMENU QSYSPRT QDDSSRC QPDDSSRC QSYSPRT QPNLSRC QSYSPRT QDDSSRC QPDDSSRC QAQA00xxxx QAQA00xxxx QPQAPRT QRJESRC QRJESRC QRJESRC QRPGLESRC QSYSPRT QRPGSRC QSYSPRT QRPGSRC QSYSPRT QCSRC QSYSPRT QCSRC QSYSPRT QLBLSRC QSYSPRT QCBLLESRC QSYSPRT QFTNSRC QSYSPRT File type PRTF PF PRTF PF PRTF PF PF PRTF PRTF PF PRTF PRTF PF PRTF PF PRTF LF PF PRTF PF PF PF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF PF PRTF File usage DDS source listing printer file. DDS source default input file. DDS source listing printer file.
1 1

Default menu source input file. Menu source listing printer file.
1

DDS source created for menu by $BMENU. DDS source created for menu by $BMENU. $BMENU source listing printer file. Pascal source listing printer file. DDS source default input file. DDS source listing printer file.
1 1 1

Program source listing printer file.

Default panel group source input file. Panel group source listing printer file. DDS source default input file. DDS source listing printer file. Q & A database model files. Q & A database model files. Q & A printer file. DDS source file used to create RJE BSC file. DDS source file used to create RJE BSC or RJE communications file. DDS source file used to create RJE communications file. ILE RPG source default input file. ILE RPG source listing printer file. RPG source default input file. RPG source listing printer file. RPG source default input file. RPG source listing printer file. SQL C source file. SQL C printer file. SQL C source file. SQL C printer file.
1 1 1 1 1 2 2 1 1

SQL COBOL source file. SQL COBOL printer file. SQL COBOL source file. SQL COBOL printer file.
1 1

SQL FORTRAN source file. SQL FORTRAN printer file.

1

Control language

129

Table 22. Files used by CL commands (part 1) (continued) Command name CRTSQLPLI File library QGPL QSYS CRTSQLRPG QGPL QSYS CRTSQLRPGI QGPL QSYS CRTSRVPGM CRTS36CBL QSYS #LIBRARY QSYS CRTS36DSPF QGPL QGPL QSSP CRTS36MNU QGPL QGPL QSSP CRTS36RPG #LIBRARY QSYS CRTS36RPGR CRTS36RPT #LIBRARY #LIBRARY QSYS CRTTAPCGY QUSRSYS QUSRSYS CRTTBL CVTPFRDTA QGPL QPFR File name QPLISRC QSYSPRT QRPGSRC QSYSPRT QRPGLESRC QSYSPRT QSYSPRT QS36SRC QSYSPRT QDDSSRC QS36DDSSRC QPUTSFGR QDDSSRC QS36DDSSRC QPUTMENU QS36SRC QSYSPRT QS36SRC QS36SRC QSYSPRT QATACGY QLTACGY QTBLSRC QACPxxxx File type PF PRTF PF PRTF PF PRTF PRTF PF PRTF PF PF PRTF PF PF PRTF PF PRTF PF PF PRTF PF LF PF PF File usage SQL PLI source file. SQL PLI printer file. SQL RPG source file. SQL RPG printer file. SQL RPG source file. SQL RPG printer file.
1 1 1 1

Service program source listing printer file. S/36-compatible COBOL source default input file. S/36-compatible COBOL source listing printer file. 1 DDS source created for display file by $SFGR. DDS source created for display file by $SFGR. $SFGR source listing printer file.

DDS source created for menu by $BMENU. DDS source created for menu by $BMENU. $BMENU source listing printer file. System/36 RPG II source default input file. System/36 RPG II source listing printer file.
1

System/36 RPG II source default input file. System/36 RPG II Auto Report source default input file. System/36 RPG II Auto Report source listing printer file. 1 Library device database file. Library device logical database file. Table source default input file. QACPxxxx performance data collection files, where xxxx = CNFG, GPHF, PROF, and RESP. Performance data collection file: job and Licensed Internal Code task data. QAPMyyyy performance data collection files, where yyyy = CIOP, CONF, DIOP, DISK, JOBS, LIOP, POOL, RESP, RWS, and SYS. 2 QAPMzzzz performance data collection files, where zzzz = ASYN, BSC, BUS, DMPT, ECL, ETH, HDLC, MIOP, and X25. 2 Performance data collection file for functional area data.

QPFR QSYS

QAITMON QAPMyyyy

PF PF

QSYS

QAPMzzzz

PF

QPFR

QAPTAPGP

PF

130

System i: Programming Control language

Table 22. Files used by CL commands (part 1) (continued) Command name CVTRPGSRC File library QSYS user-lib user-lib user-lib DLTALR DLTPFRDTA QUSRSYS QPFR QSYS File name QSYSPRT QRNCVTLG QRPGLESRC QRPGSRC QAALERT QAPGSUMD QAPMxxxx File type PRTF PF PF PF PF PF PF File usage ILE RPG listing printer file. ILE RPG conversion log file. ILE RPG source file (to file). RPG/400 source file (from file). Alert database file. Performance data collection file for graphics data. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, BUS, CIOP, CONF, DIOP, DISK, DMPT, ECL, ETH, HDLC, IOBS, JOBS, LIOP, MIOP, POOL, RESP, RWS, SBSD, SYS, TSK, and X25. 2 Performance data collection file: lock and seizure conflict data. QTRxxxx performance data collection files, where xxxxx = IDX, JOBT, JSUM, SLWT, and TSUM. All 8 of the QASXxxxx files for the DLTPRB command are the same subset of files that are shown in the QUSRSYS library for the DSPPRB command. Q & A printer file. Q & A printer file. Library device database file. Library device logical database file. CL program dump printer file. Service dump printer file. Service dump printer file. Service dump printer file. Tape dump printer file. Performance trace file. SDA source printer file. Display access codes printer file.
1 1

QPFR QPFR

QAPTLCKD QTRxxxx

PF PF

DLTPRB

QUSRSYS

QASXxxxx

PF

DLTQST DLTQSTDB DLTTAPCGY

QSYS QSYS QUSRSYS QUSRSYS

QPQAPRT QPQAPRT QATACGY QLTACGY QPPGMDMP QPSRVDMP QPSRVDMP QPSRVDMP QPTAPDMP QAPMDMPT QSYSPRT QSYSPRT QSYSPRT QAPTDDS QAPTPAGD

PRTF PRTF PF LF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PRTF PF PF

DMPCLPGM DMPJOB DMPOBJ DMPSYSOBJ DMPTAP DMPTRC

QSYS QSYS QSYS QSYS QSYS QSYS QSYS

DSPACC DSPACCAUT DSPACCGRP

QSYS QSYS QPFR QPFR

Display access code authority printer file. Performance data DDS source file.

Performance data collection file: data about files and programs in a process access group (PAG). Display process access group printer file.
1

QPFR QPFR DSPACTPJ QSYS

QPPTPAG QPPTPAGD QSYSPRT

PRTF PRTF PRTF

Performance printer file containing files and programs in a process access group (PAG). Display active prestart jobs printer file.
1

Control language

131

Table 22. Files used by CL commands (part 1) (continued) Command name DSPAPPNINF File library QUSRSYS File name QALSxxx File type PF File usage Set of 4 QALSxxx model database files that contain the record formats used for storing APPN information, where xxx = DIR, END, INM, and TDB. 2 Display APPN information printer file.
1

QSYS DSPAUTHLR QSYS

QSYSPRT QADSHLR

PRTF PF

Model database file that contains the record format for the authority holder object entries. 2 Display authority holders printer file.
1

QSYS DSPAUTL QSYS QSYS DSPAUTLDLO DSPAUTLOBJ QSYS QSYS

QPSYDSHL QAOBJAUT QPOBJAUT QSYSPRT QADALO

PRTF PF PRTF PRTF PF

Model database file that contains the record format for the authorization list entries. 2 Authorization list entries printer file. Authorization list printer file.
1 1

Model database file that contains the record format for the authorization list object entries. 2 Display authorization list objects printer file.
1

QSYS DSPAUTUSR DSPBCKSTS DSPBCKUP DSPBCKUPL DSPBKP DSPBNDDIR QSYS QSYS QSYS QSYS QSYS QSYS QSYS DSPCFGL DSPCHT DSPCLS DSPCMD DSPCNNL DSPCNNSTS DSPCOSD DSPCSI DSPCTLD DSPDBG DSPDBR QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QPSYDALO QPAUTUSR QSYSPRT QSYSPRT QSYSPRT QPDBGDSP QABNDBND QSYSPRT QPDCCFGL QPGDDM QPDSPCLS QPCMD QPDCCNNL QSYSPRT QPDCCOS QSYSPRT QPDCCTL QPDBGDSP QADSPDBR

PRTF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PF

Authorized users printer file.

1 1 1

Display backup status printer file.

1

Display backup options printer file. Display backup list printer file.

Breakpoint (debug mode) printer file.

Model database file that contains the record format for the binding directory entries. 2 Displays the contents of the binding directory printer file. 1 Configuration list printer file.
1 1 1 1

BGU-defined chart output printer file. Class printer file.

Command values printer file. Connection list printer file.

1

Connection status printer file.

1 1

Class-of-service description printer file.

Communications side information printer file. 1 Controller description printer file.

1 1

Debug display (debug mode) printer file.

Model database file that defines the record format of the file created to store information about database file relationships. 2 Printer file that contains information about database file relationships. 1

QSYS

QPDSPDBR

PRTF

132

System i: Programming Control language

Table 22. Files used by CL commands (part 1) (continued) Command name DSPDDMF DSPDEVD File library QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS DSPDLOAUT DSPDLONAM DSPDSTL QSYS QSYS QSYS QSYS QSYS DSPDSTCLGE DSPDSTLOG DSPDSTSRV QSVMSS QSYS QSYS QUSRSYS QUSRSYS QUSRSYS DSPDTA QIDU QSYS QSYS DSPDTAARA DSPDTADCT DSPEDTD DSPFD QSYS QSYS QSYS File name QPDSPDDM QPDCDEV QAOSDIRO QAOSDIRB QAOSDIRF QAOSDIRX QPDSPDDL QPDSPDSM QSYSPRT QSYSPRT QAOSDSTO QPDSPLDL QPDSPLSM QACQFVOF QPDSTDLG QPDSTSRV QASNADSA QASNADSQ QASNADSR QDTAPRT QPDZDTALOG QPDZDTAPRT QPDSPDTA QPDSPFFD QPDCEDSP File type PRTF PRTF PF PF PF PF PRTF PRTF PRTF PRTF PF PRTF PRTF PF PRTF PRTF PF PF PF PRTF PRTF PRTF PRTF PRTF PRTF File usage Distributed data management (DDM) file listing printer file. 1 Device description printer file. Display directory output file: OUTFILFMT(*TYPE1) Display directory output file: OUTFILFMT(*TYPE2) DETAIL(*BASIC) Display directory output file: OUTFILFMT(*TYPE2) DETAIL(*FULL) Display directory output file: OUTFILFMT(*TYPE3) DETAIL(*FULL) Printer file for full details of displayed directory entries. 1 Printer file for basic details of displayed directory entries. 1 Display document library object authority printer file. 1 Display document library object printer file.
1 1

Distribution list output file. Distribution list details printer file.

1 1

Distribution list summary printer file.

Output file model for MSS/400 Display Distribution Catalog Entries command. 2 Display distribution log printer file. Distribution services printer file.
1 1

SNADS secondary node ID table. SNADS destination queues table. Routing table database file. DFU audit control printer file. DFU runtime audit log. DFU runtime printer data file. Data area printer file.
1 1 1

Data dictionary printer file. Edit description printer file.

For the DSPFD command, all of the following entries having a file type of PF are physical files (model files that are not actual output files) that define the record formats of created files used to store a specific type of information about a type (or group) of files. Therefore, the common part of each model files description begins here and the unique part of each description continues under the File usage column: QSYS QSYS QAFDACCP QAFDBASI PF PF ...access path file information.
2 2

...basic file information common to all files.

Control language

133

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS DSPFFD QSYS

QAFDBSC QAFDCMN QAFDCSEQ QAFDCST QAFDDDM QAFDDSP QAFDICF QAFDJOIN QAFDLGL QAFDMBR QAFDMBRL QAFDNGP QAFDPHY QAFDPRT QAFDRFMT QAFDSAV QAFDSELO QAFDSPOL QAFDTAP QAFDTRG QPDSPFD QADSPFFD

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PRTF PF

...BSC file and mixed file device attribute information. 2 ...communications file and mixed file device attribute information. 2 ... collating sequence information.
2 2

... constraint relationship information.

...distributed data management (DDM) file attribute information. 2 ...display file and mixed file display device attribute information. 2 ...ICF file attribute information. ...join logical file information.
2 2 2

...logical file attribute information. ...database member information.

2 2

...database member list information. ... node group information.

...physical file attribute information. ...printer file attribute information. ...record format information. ...save file information.
2 2 2 2 2

...select/omit information.

...device file spooled information. ...tape file attribute information. ... trigger information.
2 1 2

File description printer file.

Model database file that defines the record format of the file created to store file field descriptions. 2 File field description printer file.
1

QSYS DSPFLR QSYS QSYS QSYS DSPFNTRSCA DSPGDF DSPGNDDIR DSPHDWRSC QSYS QSYS QSYS

QPDSPFFD QADSPDOC QADSPFLR QPDSPFLR QPDSPFNT QPGDDM QABNDBND

PRTF PF PF PRTF PRTF PRTF PF

Document list output database file. Folder list output database file. Display folder printer file.
1 1 1

Font resource attributes printer file.

1

BGU-defined graphics data printer file. System-supplied output file.

For the DSPHDWRSC command, all of the following entries having a file type of PF are physical files (model files that are not actual output files) that define the record formats of created files used to store a specific type of hardware resource information. Therefore, the common part of each model files description begins here and the unique part of each description continues under the File usage column: QSYS QSYS QSYS QSYS QARZDCMN QARZDLWS QARZDPRC QARZDTRA PF PF PF PF ...communications resources.
2 2 2

...local workstation resources. ...processor resources.

...token-ring local area network (TRLAN) adapter resources. 2

134

System i: Programming Control language

QSYS QSYS DSPHFS DSPHSTGPH DSPIGCDCT DSPJOB DSPJOBD DSPJOBLOG QSYS QPFR QSYS QSYS QSYS QSYS QSYS QSYS QSYS DSPJRN

QARZDSTG QSYSPRT QSYSPRT QPPGGPH QPDSPDCT QPDSPJOB QPRTJOBD QPJOBLOG QPJOBLOGO QAMHJLPR QAMHJLSC

PF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PF PF

...storage device resources.

2 1

Hardware resources printer file.

1

Display hierarchical file systems printer file. Display historical graph printer file. DBCS printer file.
1 1 1 1

Display job printer file.

1

Job description printer file. Job log printer file.

Job log printer file for jobs before Version 2 Release 3 of the AS/400 . 1 Primary job log model file.
2 2

Secondary job log model file.

All of the following files for the DSPJRN command having a file type of PF are physical files (model files, not actual output files) that define the record formats of files created to store a group of journal entries retrieved and converted from journal receivers. The retrieved group of entries can be a specific type of information or all types of information that was journaled. Each created file stores the retrieved journal entries after they are converted into one of four basic formats (*TYPE1, *TYPE2, *TYPE3 or *TYPE4) or into the format defined for the specific type of data being retrieved. v *TYPE1: the basic file format is described in the Journal Management topic collection. v *TYPE2: all of *TYPE1 plus the user profile field. v *TYPE3: all of *TYPE2 plus the null value indicators. v *TYPE4: all of *TYPE3 plus the JID, referential integrity, and trigger information. v *TYPE5: all of *TYPE4 plus more information. v Type-dependent format - the format associated with the specific type (as described as follows for the fourth and following files) of information being retrieved. For example, the model file QASY AFJE has a unique format for storing all retrieved journal entries related to authority failures ( AF) on the system. For the DSPJRN PF files listed as follows, the common part of all the model files descriptions begins here and the unique part of each files description continues under the File usage column: QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QADSPJRN QADSPJR2 QADSPJR3 QADSPJR4 QADSPJR5 QADXERLG QADXERL4 QADXJRNL QADXJRN4 QAJBACG PF PF PF PF PF PF PF PF PF PF ...a specific type (or all types) of information; stored in the *TYPE1 format. ...a specific type (or all types) of information; stored in the *TYPE2 format. ...a specific type (or all types) of information; stored in the *TYPE3 format. ...a specific type (or all types) of information; stored in the *TYPE4 format. ...a specific type (or all types) of information; stored in the *TYPE5 format. ...DSNX logged errors.
2 2

...DSNX logged errors; stored in the *TYPE4 format. 2 ...DSNX logged data.
2

...DSNX logged data; stored in the *TYPE4 format. 2 ...job accounting.

2

Control language

135

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QAJBACG4 QALZALK QALZALK4 QALZALL QALZALL4 QALZALU QALZALU4 QAPTACG QAPTACG4 QAPTACG5 QASYADJE QASYADJ4 QASYADJ5 QASYAFJE QASYAFJ4 QASYAFJ5 QASYAPJE QASYAPJ4 QASYAPJ5 QASYAUJ5 QASYCAJE QASYCAJ4 QASYCAJ5 QASYCDJE QASYCDJ4 QASYCDJ5 QASYCOJE QASYCOJ4

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...job accounting; stored in the *TYPE4 format. 2 ...invalid license keys.

2

...invalid license keys; stored in the *TYPE4 format. 2 ...usage limit increases.
2

...usage limit increases; stored in the *TYPE4 format. 2 ...licensed users that exceed usage limits. ...licensed users that exceed usage limits; stored in the *TYPE4 format. 2 ...print job accounting.
2 2

...print job accounting; stored in the *TYPE4 format. 2 ...print job accounting; stored in the *TYPE5 format. 2 ...changes to auditing attributes.
2

...changes to auditing attributes; stored in the *TYPE4 format. 2 ...changes to auditing attributes; stored in the *TYPE5 format. 2 ...authority failures.
2

...authority failures; stored in the *TYPE4 format. 2 ...authority failures; stored in the *TYPE5 format. 2 ...use of adopted authority.
2

...use of adopted authority; stored in the *TYPE4 format. 2 ...use of adopted authority; stored in the *TYPE5 format. 2 ...security attribute changed; stored in the *TYPE5 format. 2 ...changes to object authority (authorization list or object). 2 ...changes to object authority (authorization list or object); stored in the *TYPE4 format. 2 ...changes to object authority (authorization list or object); stored in the *TYPE5 format. 2 ...command strings.
2

...command strings; stored in the *TYPE4 format. 2 ...command strings; stored in the *TYPE5 format. 2 ...objects created on the system.
2

...objects created on the system; stored in the *TYPE4 format. 2

136

System i: Programming Control language

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYCOJ5 QASYCPJE QASYCPJ4 QASYCPJ5 QASYCQJE QASYCQJ4 QASYCQJ5 QASYCUJ4 QASYCUJ5 QASYCVJ4 QASYCVJ5 QASYCYJ4 QASYCYJ5 QASYDIJ4 QASYDIJ5 QASYDOJE QASYDOJ4 QASYDOJ5 QASYDSJE QASYDSJ4 QASYDSJ5 QASYEVJ4 QASYEVJ5 QASYGRJ4 QASYGRJ5 QASYGSJE

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...objects created on the system; stored in the *TYPE5 format. 2 ...create, change, and restore user profile operations. 2 ...create, change, and restore user profile operations; stored in the *TYPE4 format. ...create, change, and restore user profile operations; stored in the *TYPE5 format. ...changes to *CRQD object.
2 2

...changes to *CRQD object; stored in the *TYPE4 format. 2 ...changes to *CRQD object; stored in the *TYPE5 format. 2 ...cluster operation; stored in the *TYPE4 format. 2 ...cluster operation; stored in the *TYPE5 format. 2 ...connection verification; stored in the *TYPE4 format. 2 ...connection verification; stored in the *TYPE5 format. 2 ...Cryptographic configuration; stored in the *TYPE4 format. 2 ...Cryptographic configuration; stored in the *TYPE5 format. 2 ...Directory services; stored in the *TYPE4 format. 2 ...Directory services; stored in the *TYPE5 format. 2 ...objects deleted from the system.
2

...objects deleted from the system; stored in the *TYPE4 format. 2 ...objects deleted from the system; stored in the *TYPE5 format. 2 ...resetting the DST security officer password. 2 ...resetting the DST security officer password; stored in the *TYPE4 format. ...resetting the DST security officer password; stored in the *TYPE5 format. ...Environment variable; stored in the *TYPE4 format. 2 ...Environment variable; stored in the *TYPE5 format. 2 ...General purpose audit record; stored in the *TYPE4 format. 2 ...General purpose audit record; stored in the *TYPE5 format. 2 ...gives of descriptors.
2 2

Control language

137

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYGSJ4 QASYGSJ5 QASYIPJE QASYIPJ4 QASYIPJ5 QASYIRJ4 QASYIRJ5 QASYISJ5 QASYJDJE QASYJDJ4 QASYJDJ5 QASYJSJE QASYJSJ4 QASYJSJ5 QASYKFJ4 QASYKFJ5 QASYLDJE QASYLDJ4 QASYLDJ5 QASYMLJE QASYMLJ4 QASYMLJ5 QASYNAJE QASYNAJ4 QASYNAJ5 QASYNDJE QASYNDJ4

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...gives of descriptors; stored in the *TYPE4 format. 2 ...gives of descriptors; stored in the *TYPE5 format. 2 ...interprocess communications.
2

...interprocess communications; stored in the *TYPE4 format. 2 ...interprocess communications; stored in the *TYPE5 format. 2 ...IP rules actions; stored in the *TYPE4 format. 2 ...IP rules actions; stored in the *TYPE5 format. 2 ...Internet security management; stored in the *TYPE5 format. 2 ...changes to the USER parameter of job descriptions. 2 ...changes to the USER parameter of job descriptions; stored in the *TYPE4 format. ...changes to the USER parameter of job descriptions; stored in the *TYPE5 format. ...job changes.
2 2 2

...job changes; stored in the *TYPE4 format. ...job changes; stored in the *TYPE5 format.
2

...Key ring file; stored in the *TYPE4 format.

2

...Key ring file; stored in the *TYPE5 format.

2

...link/unlink/lookup directory.

...link/unlink/lookup directory; stored in the *TYPE4 format. 2 ...link/unlink/lookup directory; stored in the *TYPE5 format. 2 ...mail actions.
2 2

...mail actions; stored in the *TYPE4 format. ...mail actions; stored in the *TYPE5 format.
2

...changes to network attributes.

...changes to network attributes; stored in the *TYPE4 format. 2 ...changes to network attributes; stored in the *TYPE5 format. 2 ...directory search violations.
2

...directory search violations; stored in the *TYPE4 format. 2

138

System i: Programming Control language

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYNDJ5 QASYNEJE QASYNEJ4 QASYNEJ5 QASYOMJE QASYOMJ4 QASYOMJ5 QASYORJE QASYORJ4 QASYORJ5 QASYOWJE QASYOWJ4 QASYOWJ5 QASYO1JE QASYO1J4 QASYO1J5 QASYO2JE QASYO2J4 QASYO2J5 QASYO3JE QASYO3J4 QASYO3J5 QASYPAJE QASYPAJ4

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...directory search violations; stored in the *TYPE5 format. 2 ...end point violations.
2

...end point violations; stored in the *TYPE4 format. 2 ...end point violations; stored in the *TYPE5 format. 2 ...object move and rename operations. ...object move and rename operations; stored in the *TYPE4 format. 2 ...object move and rename operations; stored in the *TYPE5 format. 2 ...object restore operations.
2 2

...object restore operations; stored in the *TYPE4 format. 2 ...object restore operations; stored in the *TYPE5 format. 2 ...changes to object ownership.
2

...changes to object ownership; stored in the *TYPE4 format. 2 ...changes to object ownership; stored in the *TYPE5 format. 2 ...single optical object accesses.
2

...single optical object accesses; stored in the *TYPE4 format. 2 ...single optical object accesses; stored in the *TYPE5 format. 2 ...dual optical object accesses.
2

...dual optical object accesses; stored in the *TYPE4 format. 2 ...dual optical object accesses; stored in the *TYPE5 format. 2 ...optical volume accesses.
2

...optical volume accesses; stored in the *TYPE4 format. 2 ...optical volume accesses; stored in the *TYPE5 format. 2 ...changes to programs (CHGPGM) that will now adopt the owners authority. 2 ...changes to programs (CHGPGM) that will now adopt the owners authority; stored in the *TYPE4 format. 2 ...changes to programs (CHGPGM) that will now adopt the owners authority; stored in the *TYPE5 format. 2 ...changes to object primary group.
2

QSYS

QASYPAJ5

PF

QSYS QSYS

QASYPGJE QASYPGJ4

PF PF

...changes to object primary group; stored in the *TYPE4 format. 2

Control language

139

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYPGJ5 QASYPOJE QASYPOJ4 QASYPOJ5 QASYPSJE QASYPSJ4 QASYPSJ5 QASYPWJE QASYPWJ4

PF PF PF PF PF PF PF PF PF

...changes to object primary group; stored in the *TYPE5 format. 2 ...printer output actions.
2

...printer output actions; stored in the *TYPE4 format. 2 ...printer output actions; stored in the *TYPE5 format. 2 ...profile swapping.
2

...profile swapping; stored in the *TYPE4 format. 2 ...profile swapping; stored in the *TYPE5 format. 2 ...attempted usage of invalid passwords or user profile names. 2 ...attempted usage of invalid passwords or user profile names; stored in the *TYPE4 format. 2 ...attempted usage of invalid passwords or user profile names; stored in the *TYPE5 format. 2 ...restore of objects when authority changes.
2

QSYS

QASYPWJ5

PF

QSYS QSYS QSYS QSYS QSYS

QASYRAJE QASYRAJ4 QASYRAJ5 QASYRJJE QASYRJJ4

PF PF PF PF PF

...restore of objects when authority changes; stored in the *TYPE4 format. 2 ...restore of objects when authority changes; stored in the *TYPE5 format. 2 ...restore of job descriptions that contain user profile names. 2 ...restore of job descriptions that contain user profile names; stored in the *TYPE4 format. 2 ...restore of job descriptions that contain user profile names; stored in the *TYPE5 format. 2 ...restore of objects when ownership was changed to QDFTOWN. 2 ...restore of objects when ownership was changed to QDFTOWN; stored in the *TYPE4 format. 2 ...restore of objects when ownership was changed to QDFTOWN; stored in the *TYPE5 format. 2 ...restore of programs that adopt their owners authority. 2 ...restore of programs that adopt their owners authority; stored in the *TYPE4 format. 2 ...restore of programs that adopt their owners authority; stored in the *TYPE5 format. 2

QSYS

QASYRJJ5

PF

QSYS QSYS

QASYROJE QASYROJ4

PF PF

QSYS

QASYROJ5

PF

QSYS QSYS

QASYRPJE QASYRPJ4

PF PF

QSYS

QASYRPJ5

PF

140

System i: Programming Control language

QSYS QSYS QSYS QSYS QSYS

QASYRQJE QASYRQJ4 QASYRQJ5 QASYRUJE QASYRUJ4

PF PF PF PF PF

...restores of *CRQD object.

...restores of *CRQD object; stored in the *TYPE4 format. 2 ...restores of *CRQD object; stored in the *TYPE5 format. 2 ...operations restoring authority for user profiles, using the RSTAUT command. 2 ...operations restoring authority for user profiles, using the RSTAUT command; stored in the *TYPE4 format. 2 ...operations restoring authority for user profiles, using the RSTAUT command; stored in the *TYPE5 format. 2 ...changes on primary group restores.
2

QSYS

QASYRUJ5

PF

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYRZJE QASYRZJ4 QASYRZJ5 QASYSDJE QASYSDJ4 QASYSDJ5 QASYSEJE QASYSEJ4 QASYSEJ5 QASYSFJE QASYSFJ4 QASYSFJ5 QASYSGJ4 QASYSGJ5 QASYSKJ4 QASYSKJ5 QASYSMJE QASYSMJ4 QASYSMJ5 QASYSOJE

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...changes on primary group restores; stored in the *TYPE4 format. 2 ...changes on primary group restores; stored in the *TYPE5 format. 2 ...changes to the system distribution directory. 2 ...changes to the system distribution directory; stored in the *TYPE4 format. ...changes to the system distribution directory; stored in the *TYPE5 format. ...changes to subsystem routings.
2 2

...changes to subsystem routings; stored in the *TYPE4 format. 2 ...changes to subsystem routings; stored in the *TYPE5 format. 2 ...actions with spooled files.
2

...actions with spooled files; stored in the *TYPE4 format. 2 ...actions with spooled files; stored in the *TYPE5 format. 2 ...Asynchronous signals; stored in the *TYPE4 format. 2 ...Asynchronous signals; stored in the *TYPE5 format. 2 ...secure sockets connections; stored in the *TYPE4 format. 2 ...secure sockets connections; stored in the *TYPE5 format. 2 ...system management changes.
2

...system management changes; stored in the *TYPE4 format. 2 ...system management changes; stored in the *TYPE5 format. 2 ...server security changes.
2

Control language

141

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYSOJ4 QASYSOJ5 QASYSTJE QASYSTJ4 QASYSTJ5 QASYSVJE QASYSVJ4 QASYSVJ5 QASYVAJE QASYVAJ4 QASYVAJ5 QASYVCJE QASYVCJ4 QASYVCJ5 QASYVFJE QASYVFJ4 QASYVFJ5 QASYVLJE QASYVLJ4 QASYVLJ5 QASYVNJE QASYVNJ4 QASYVNJ5 QASYVOJ4 QASYVOJ5 QASYVPJE QASYVPJ4 QASYVPJ5

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...server security changes; stored in the *TYPE4 format. 2 ...server security changes; stored in the *TYPE5 format. 2 ...use of system service tools.
2

...use of system service tools; stored in the *TYPE4 format. 2 ...use of system service tools; stored in the *TYPE5 format. 2 ...changes to system values.
2

...changes to system values; stored in the *TYPE4 format. 2 ...changes to system values; stored in the *TYPE5 format. 2 ...changes to access control list.
2

...changes to access control list; stored in the *TYPE4 format. 2 ...changes to access control list; stored in the *TYPE5 format. 2 ...connection starts and ends.
2

...connection starts and ends; stored in the *TYPE4 format. 2 ...connection starts and ends; stored in the *TYPE5 format. 2 ...closes of server files.
2

...closes of server files; stored in the *TYPE4 format. 2 ...closes of server files; stored in the *TYPE5 format. 2 ...exceeding account limit.
2

...exceeding account limit; stored in the *TYPE4 format. 2 ...exceeding account limit; stored in the *TYPE5 format. 2 ...network logons and logoffs.
2

...network logons and logoffs; stored in the *TYPE4 format. 2 ...network logons and logoffs; stored in the *TYPE5 format. 2 ...actions on validation lists; stored in the *TYPE4 format. 2 ...actions on validation lists; stored in the *TYPE5 format. 2 ...network password errors.
2

...network password errors; stored in the *TYPE4 format. 2 ...network password errors; stored in the *TYPE5 format. 2

142

System i: Programming Control language

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QASYVRJE QASYVRJ4 QASYVRJ5 QASYVSJE QASYVSJ4 QASYVSJ5 QASYVUJE QASYVUJ4 QASYVUJ5 QASYVVJE QASYVVJ4 QASYVVJ5 QASYXOJ4 QASYXOJ5 QASYYCJE QASYYCJ4 QASYYCJ5 QASYYRJE QASYYRJ4 QASYYRJ5 QASYZCJE QASYZCJ4 QASYZCJ5 QASYZMJE QASYZMJ4 QASYZRJE QASYZRJ4 QASYZRJ5

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF

...accesses to network resources.

...accesses to network resources; stored in the *TYPE4 format. 2 ...accesses to network resources; stored in the *TYPE5 format. 2 ...server session starts and ends.
2

...server session starts and ends; stored in the *TYPE4 format. 2 ...server session starts and ends; stored in the *TYPE5 format. 2 ...changes to network profiles.
2

...changes to network profiles; stored in the *TYPE4 format. 2 ...changes to network profiles; stored in the *TYPE5 format. 2 ...changes to service status.
2

...changes to service status; stored in the *TYPE4 format. 2 ...changes to service status; stored in the *TYPE5 format. 2 ...network authentication; stored in the *TYPE4 format. 2 ...network authentication; stored in the *TYPE5 format. 2 ...changes to document library objects. ...changes to document library objects; stored in the *TYPE4 format. 2 ...changes to document library objects; stored in the *TYPE5 format. 2 ...read operations of document library objects. 2 ...read operations of document library objects; stored in the *TYPE4 format. 2 ...read operations of document library objects; stored in the *TYPE5 format. 2 ...changes to objects.
2 2

...changes to objects; stored in the *TYPE4 format. 2 ...changes to objects; stored in the *TYPE5 format. 2 ...object method access.
2

...object method access; stored in the *TYPE4 format. 2 ...read operations of objects.
2

...read operations of objects; stored in the *TYPE4 format. 2 ...read operations of objects; stored in the *TYPE5 format. 2
Control language

143

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QATOFIPF QATOFNAT QATOQQOS QATOSLOG QATOSLOG QATOVSOF QAWCTPJE QAWCTPJ4 QAZDALLG QAZDCFLG QAZDCFL4

PF PF PF PF PF PF PF PF PF PF PF

...IP filter rule actions. ...IP NAT rule actions.

2

2 2 2

...modification of QoS policies. ...SNMP log entries.

...SNMP log entries; stored in the *TYPE4 format. 2 ...VPN information.

2 2

...performance tuning.

...performance tuning; stored in the *TYPE4 format. 2 ...SNADS alert logging.

2

...configuration changes to SNADS distribution queues table. 2 ...configuration changes to SNADS distribution queues table; stored in the *TYPE4 format. 2 ...SNADS logged errors.
2

QSYS QSYS QSYS QSYS QSYS QSYS

QAZDERLG QAZDERL4 QAZDJRNL QAZDJRN4 QAZDRTLG QAZDRTL4

PF PF PF PF PF PF

...SNADS logged errors; stored in the *TYPE4 format. 2 ...SNADS logged data.
2

...SNADS logged data; stored in the *TYPE4 format. 2 ...changes to SNADS routing and secondary system name tables. 2 ...changes to SNADS routing and secondary system name tables; stored in the *TYPE4 format. 2 ...SNADS miscellaneous logged system-level occurrences. 2 ...SNADS miscellaneous logged system-level occurrences; stored in the *TYPE4 format. 2 ...Mail server framework (MSF) configuration changes logging. 2 ...Mail server framework (MSF) configuration changes logging; stored in the *TYPE4 format. 2 ...Mail server framework (MSF) error logging. 2 ...Mail server framework (MSF) error logging; stored in the *TYPE4 format. ...Mail server framework (MSF) data logging. 2 ...Mail server framework (MSF) data logging; stored in the *TYPE4 format.
2 2

QSYS QSYS QSYS QSYS

QAZDSYLG QAZDSYL4 QAZMFCF QAZMFCF4

PF PF PF PF

QSYS QSYS QSYS QSYS QSYS

QAZMFER QAZMFER4 QAZMFLG QAZMFLG4 QAZMFSY

PF PF PF PF PF

...Mail server framework (MSF) system information logging. 2

144

System i: Programming Control language

QSYS

QAZMFSY4

PF

...Mail server framework (MSF) system information logging; stored in the *TYPE4 format. 2 Display journal printer file.
1

QSYS DSPJRNRCVA DSPLIB DSPLIBD DSPLIBL DSPLIND DSPLOG DSPMNUA DSPMOD QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QPDSPJRN QPDSPRCV QPDSPLIB QPRTLIBD QPRTLIBL QPDCLINE QPDSPLOG QPDSPMNU

PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF

Journal receiver attributes printer file. Library printer file.

1 1

Library description printer file. Library list printer file.

1 1

Line description printer file. Log display printer file.

1

Menu attributes printer file.

For the DSPMOD command, all of the following entries having a file type of files used to store a specific type of information about a type (or group) of files. Therefore, the common part of each model files description begins here and the unique part of each description continues under the File usage column: QSVMSS QSYS QSYS QSYS QSYS QSYS QSYS QACQSRC QABNDMBA QABNDMSI QABNDMEX QABNDMIM QABNDMPR QABNDMRE PRTF PF PF PF PF PF PF ...contains sources of example security exit programs. 1 ...basic information and compatibility sections. 1 ...decompressed size and size limits.
1

...symbols defined in this module and exported to others. 1 ...defined symbols that are external to this module. 1 ...a list of procedure names and types.
1

...a list of system objects referred to by the module at the time the module is bound into a program or service program. 1 ...module copyright information. ...module printer file.
1 1

QSYS QSYS DSPMODD DSPMODSTS DSPMSG DSPMSGD DSPNETA QSYS QSYS QSYS QSYS QSYS QSYS QSYS DSPNWID DSPOBJAUT QSYS QSYS QSYS DSPOBJD QSYS QSYS

QABNDMCO QSYSPRT QPDCMOD QPDCMOD QPDSPMSG QPMSGD QANFDNTF QPDSPNET QPNFNJE QPDCNWID QAOBJAUT QPOBJAUT QADSPOBJ QPRTOBJD

PF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PRTF PF PRTF PF PRTF

Mode description printer file. Mode status printer file.

1 1

Message display printer file.

Message description printer file.

Model database file used to define the record format for network file entries. 2 Display network attributes printer file.
1 1 1

Display network job entries printer file.

Network interface description printer file.

Model database file that defines the record format for the object authority entries. 2 Object authority printer file.
1

Model database file that defines the record format for the object description entries. 2 Object description printer file.
1

Control language

145

DSPOVR DSPPDGPRF DSPPFRGPH

QSYS QGPL QPFRDATA QPFRDATA QPFR

QPDSPOVR QPCJPDGPRF QAPGGPHF QAPGPKGF QPPGGPH QPDPGM QADPGMAD

PRTF PRTF PF PF PRTF PRTF PF

Display overrides printer file.

Printer file for print descriptor group profile. 1 Performance database file: graph format data. Performance database file: graph package data. Performance graphs printer file. Display program printer file.
1 1

DSPPGM DSPPGMADP

QSYS QSYS

Model database file that defines the record format of the file created to store the names of programs that adopt the specified profile. 2 Printer file that lists the programs that adopt the specified profile. 1 Model database file that defines the record format of the file created to store program references. 2 Printer file that contains program references. 1 Program variable (debug mode) printer file.
1

QSYS DSPPGMREF QSYS

QPPGMADP QADSPPGM

PRTF PF

QSYS DSPPGMVAR DSPPRB QSYS

QPDSPPGM QPDBGDSP

PRTF PRTF

All 8 of the QASXxxxx files shown as follows in the QUSRSYS library are also used by the DLTPRB and WRKPRB commands. The following other files (in QSYS) are not used by those commands. QSYS QASXxxxx PF Set of 5 QASXxxxx model database files that contain the layouts for problem output files, where xxxx = CAOF, FXOF, PBOF, SDOF, and TXOF. 2 Problem log detail printer file.
1 1

QSYS QSYS
3

QSXPRTD QSXPRTL QASXCALL 3 QASXDTA QASXEVT QASXFRU

3 3 3 3 3

PRTF PRTF

Problem log summary printer file.

The following 8 files are also used by the DLTPRB and WRKPRB commands. QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS PF PF PF PF PF PF PF
3

Problem log call override file. Problem log data identifier file. Problem log event file. Problem log possible cause file. Problem log user notes file. Problem log problem file. Problem log PTF file. Problem log symptom string file. Model database file that defines the record format of the file created to store program temporary fix (PTF) information. 2 Display programming temporary fix (PTF) printer file. 1 Display power schedule printer file. Record locks display printer file.
1 1

QASXNOTE QASXPROB QASXPTF

3

QASXSYMP QADSPPTF

PF PF

DSPPTF

QSYS

QSYS DSPPWRSCD DSPRCDLCK QSYS QSYS

QSYSPRT QSYSPRT QPDSPRLK

PRTF PRTF PRTF

146

System i: Programming Control language

DSPRCYAP DSPRDBDIRE

QSYS QSYS QSYS

QSYSPRT QSYSPRT QADSPDE QPRTCFGC QPSRODSP QPRTSBSD QARZLCOF

PRTF PRTF PF PRTF PRTF PRTF PF

Display recovery for access paths printer file. Distributed relational database directory printer file. 1 Model database file that defines the record format for the RDB directory entries. RJE configuration printer file.
1

DSPRJECFG DSPSAVF DSPSBSD DSPSFWRSC

QRJE QSYS QSYS QSYS

Printer file for save file save/restore information. 1 Subsystem description printer file.
1

Model database file of the file created to store information about IBM licensed programs and SystemView packaged applications. 2 Software resources printer file.
1 1

QSYS DSPSOCSTS QSYS QUSRSYS DSPSRVPGM DSPSYSSTS DSPSYSVAL DSPTAP QSYS QSYS QSYS QSYS QSYS QSYS DSPTAPCGY QSYS QSYS QUSRSYS QUSRSYS DSPTAPCTG QSYS QSYS QUSRSYS QUSRSYS DSPTAPSTS QSYS QSYS QSYS QSYS DSPTRAPRF DSPTRC DSPTRCDTA DSPTRNSTS DSPUSRPMN QSYS QSYS QSYS QSYS QSYS

QSYSPRT QSYSPRT QAALSOC QSYSPRT QPDSPSTS QPDSPSVL QPTAPDSP QPSRODSP QSYSTAP QTAPCGY QATACOF QATACGY QLTACGY QPTACTG QATAVOF QATAMID QATAMID QPTAPSTS QATAIOF QSYSTAP QPTYSWTD QSYSPRT QPDBGDSP QPDBGDSP QSYSPRT QSYSPRT

PRTF PRTF PF PRTF PRTF PRTF PRTF PRTF TAPF PRTF PF PF LF PRTF PF PF LF PRTF PF TAPF PRTF PRTF PRTF PRTF PRTF PRTF

Sphere of control status printer file. Sphere of control database file. Service program printer file.
1 1 1 1

Display system status printer file. System value printer file.

Printer file for tape output.

1

Printer file for tapes in save/restore format. Tape device file for input. Printer file for tape categories 1. Model output file for tape categories 2. Library device database file. Library device logical database file. Printer file for tape cartridge identifiers 1. Model output file for tape cartridge identifiers 2. Library device database file. Library device logical database file. Printer file for tape library Model output file for tape Tape device file or input Printer file for printing a telephony switch entry. 1 Printer file containing a token-ring network adapter profile. 1 Trace (debug mode) printer file.
1 1 1 1

Trace data (debug mode) printer file.

Token-ring network status printer file.

Display document authority printer file.

Control language

147

DSPUSRPRF

QSYS

QADSPUPA

PF

Model database file that defines the record format of user profiles for TYPE(*OBJAUT).
2

QSYS QSYS

QADSPUPB QADSPUPO

PF PF

Model database file that defines the record format of user profiles for TYPE(*BASIC). 2 Model database file that defines the record format of user profiles for TYPE(*OBJOWN). 2 User profile printer file.
1 1

QSYS DSPWSUSR DUPTAP EDTIGCDCT EDTQST EJTEMLOUT ENDDSKCOL QSYS QSYS QSYS QSYS QSYS QPFR QPFR ENDJOBTRC QPFR QPFR QPFR QPFR

QPUSRPRF QSYSPRT QSYSTAP QPDSPDCT QPQAPRT QPEMPRTF QAPTDDS QAPTDSKD QAPTDDS QAPTTRCJ QPPTTRCD QPPTTRC1

PRTF PRTF TAPF PRTF PRTF PRTF PF PF PF PF PRTF PRTF

Workstation user printer file.

Tape device file used for input and output. DBCS printer file. Q & A printer file. Emulation printer file. Performance data DDS source file. Performance data collection file: disk activity data. Performance data DDS source file. Performance data collection file: job trace data. Performance printer file containing job trace analysis detail data. Performance printer file containing job trace analysis summary data of physical disk activity. Performance printer file containing job trace analysis I/O summary data. Emulation printer file. Performance data collection file: high-level sampled address monitor (SAM) data. Performance data collection file: low-level sampled address monitor (SAM) data. Data format printer file. Sort source default input file. PDM printer output file for users find string requests. PDM printer output file for users find string requests. SNADS distribution queues table. Tape device file used for output. Tape device file used for input. Q & A supplied model database files. Q & A database model files. Q & A database model files. Q & A printer file. Merge form description printer file.
2 2 2

QPFR ENDPRTEML QSYS QPFR QPFR FMTDTA QSYS QGPL FNDSTRPART FNDSTRPDM HLDDSTQ INZTAP QPDA QPDA QUSRSYS QSYS QSYS LODQSTDB QQALIB QSYS QSYS QSYS MRGFORMD QPDA

QPPTTRC2 QPEMPRTF QAPTSAMH QAPTSAMV QSYSPRT QFMTSRC QPUOPRTF QPUOPRTF QASNADSQ QSYSTAP QSYSTAP QAQAxxxx00 QAQA00xxxx QAQA00xxxx QPQAPRT QPAPFPRT

PRTF PRTF PF PF PRTF PF PRTF PRTF PF TAPF TAPF PF LF PF PRTF PRTF

148

System i: Programming Control language

MRGTCPHT PRTACTRPT

QUSRSYS user-lib QPFR QPFR

QATOCHOST QAITMON QAPTDDS QPITACTR QSYSPRT QSYSPRT QASCCMNT

PF PF PF PRTF PRTF PRTF PF

TCP/IP hosts file. Performance data collection file: job and Licensed Internal Code task data. Performance data DDS source file. Performance printer file containing job and Licensed Internal Code task data. Advanced Function Printing data printer file. Command usage printer file. Model database file that defines the record format of the file created to store communications trace records. 2 Communications trace printer file (concurrent service monitor). 1 Performance data DDS source file. Performance printer file containing component-level activity data. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, CIOP, CONF, DIOP, DISK, ECL, ETH, HDLC, JOBS, LIOP, MIOP, POOL, RESP, RWS, and SYS. 2 Print device address printer file. Document output database file. Print document printer file.
1 1

PRTAFPDTA PRTCMDUSG PRTCMNTRC

QSYS QSYS QSYS

QSYS PRTCPTRPT QPFR QPFR QSYS

QPCSMPRT QAPTDDS QPPTCPTR QAPMxxxx

PRTF PF PRTF PF

PRTDEVADR PRTDOC

QSYS QSYS QSYS

QPDDEVA QAOPOUFL QSYSPRT QAEZDISK QAEZDISK QPEZDISK QSYSPRT QAPTDDS QAPTDSKD QPPTDSK QAPRTELG

PRTF PF PRTF PF PF PRTF PRTF PF PF PRTF PF

PRTDSKINF

QSYS QUSRSYS QSYS QSYS

Model outfile for disk space information. Database input file of disk space information. Disk space report printer file. Disk space report printer file. This file must be specified if using OVRPRTF. Performance data DDS source file. Performance database input file of disk activity collection data. Printer file of disk unit I/O activity data. Model database file that defines the record format of the file created to store error log records. 2 Model database file that defines the record format of the file created to store volume statistics. 2 Error log (for concurrent service monitor) printer file. 1 Internal data (for concurrent service monitor) printer file. Tape device file used for output. Performance data DDS source file.

PRTDSKRPT

QPFR QPFR QPFR

PRTERRLOG

QSYS

QSYS

QAVOLSTA

PF

QSYS PRTINTDTA QSYS QSYS PRTJOBRPT QPFR

QPCSMPRT QPCSMPRT QSYSTAP QAPTDDS

PRTF PRTF TAPF PF

Control language

149

QPFR QSYS PRTJOBTRC QPFR QPFR QPFR QPFR QPFR

QPPTITVJ QAPMxxxx QAJOBTRC QAPTDDS QAPTTRCJ QPPTTRCD QPPTTRC1

PRTF PF PF PF PF PRTF PRTF

Performance printer file containing job interval collection data. QAPMxxxx performance data collection files, where xxxx = CONF and JOBS. 2 Performance data collection file: job trace data. Performance data DDS source file. Performance data collection file: job trace data. Performance printer file containing job trace analysis detail data. Performance printer file containing job trace analysis summary data of physical disk activity. Performance printer file containing job trace analysis I/O summary data. Performance data collection output file containing lock and seizure conflict data. Performance data DDS source file. Performance data collection printer file containing lock and seizure conflict data. Performance data collection input file containing system lock and seizure conflict trace data. 2 Performance data DDS source file. Performance printer file containing subsystem and pool activity interval data. QAPMxxxx performance data collection files, where xxxx = CONF, JOBS, and POOL. 2 Performance data DDS source file. Performance printer file containing disk and communications line activity interval data. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, CIOP, CONF, DIOP, DISK, ECL, ETH, HDLC, LIOP, MIOP, RESP, RWS, and SYS. 2 Performance data collection file: high-level sampled address monitor (SAM) data. Performance data collection file: low-level sampled address monitor (SAM) data. Printer file of SAM performance data. Performance data DDS source file. Performance printer file containing system workload and resource utilization data. QAPMxxxx performance data collection files, where xxxx = ASYN, BSC, CONF, DISK, ECL, ETH, HDLC, JOBS, POOL, SYS, and X25. 2

QPFR PRTLCKRPT user-lib QPFR QPFR QSYS

QPPTTRC2 QAPTLCKD QAPTDDS QPPTLCK QAPMDMPT

PRTF PF PF PRTF PF

PRTPOLRPT

QPFR QPFR QSYS

QAPTDDS QPPTITVP QAPMxxxx

PF PRTF PF

PRTRSCRPT

QPFR QPFR

QAPTDDS QPPTITVR

PF PRTF

QSYS

QAPMxxxx

PF

QPFR QPFR QPFR PRTSYSRPT QPFR QPFR QSYS

QAPTSAMH QAPTSAMV QPPTSAM QAPTDDS QPPTSYSR QAPMxxxx

PF PF PRTF PF PRTF PF

150

System i: Programming Control language

PRTTNSRPT

QPFR QPFR QPFR QPFR QSYS

QAPTDDS QPSPDJS QPSPDTD QPSPDTS QAPMxxxx QPSRVTRC QTRTJOBT QAPTDDS QAPMDMPT QAOSIQDL QAOSILIN QAOSILOT QPRCLDMP QAOSIRCV QPTIRCV QASNADSQ QASNADSQ QASNADSR QASNADSQ QASNADSR QASNADSA QAJRNCHG QANFNJE QAALSOC QATAMID QLTAMID QATACGY QLTACGY QATOCHOST QATOCIFC QATOCPORT QATOCRSI QATOCRTE QATOCHOST QSYSTAP QASRRSTO

PF PRTF PRTF PRTF PF PRTF PF PF PF PF PF PF PRTF PF PRTF PF PF PF PF PF PF PF PF PF PF LF PF LF PF PF PF PF PF PF TAPF PF

Performance data DDS source file. Performance printer file containing job summary data. Performance printer file containing job state transition data. Performance printer file containing job transaction data. QAPMxxxx performance data collection files, where xxxx = DMPT and JOBS. 2 Job trace printer output file.
1

PRTTRC PRTTRCRPT

QSYS user-lib QPFR QSYS

Performance data collection input file containing batch job trace data. Performance data DDS source file. Performance data collection input file containing system trace data. 2 Query document library output file. Incoming distribution output file. Outgoing distribution output file. Reclaim dump output listing. Receive incoming mail distribution model database file. 2 Received files summary printer file. SNADS distribution queues table. SNADS distribution queues table. SNADS routing table. SNADS distribution queues table. SNADS routing table. SNADS secondary node ID table. Model output file for remove journaled changes. Network job entry database file. Sphere of control file. Cartridge ID database file. Cartridge ID logical database file. Category database file. Category logical file. TCP/IP host file. TCP/IP interface file. TCP/IP port restrictions file. TCP/IP remote system information file. TCP/IP route file. TCP/IP host file. Tape device file used for input. Model output file for configuration.
2 1

QRYDOCLIB QRYDST

QSYS QSYS QSYS

RCLSTG RCVDST RCVTIEF RLSDSTQ RMVDSTQ

QSYS QSYS QSYS QUSRSYS QUSRSYS QUSRSYS

RMVDSTRTE

QUSRSYS QUSRSYS

RMVDSTSYSN RMVJRNCHG RMVNETJOBE RMVSOCE RMVTAPCTG

QUSRSYS QSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS

RMVTCPHTE RMVTCPIFC RMVTCPPORT RMVTCPRSI RMVTCPRTE RNMTCPHTE RST RSTCFG

QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QSYS QSYS

Control language

151

QSYS QSYS RSTDLO QSYS QSYS QSYS RSTLIB QSYS QSYS QSYS RSTLICPGM QSYS QSYS RSTOBJ QSYS QSYS QSYS RSTUSRPRF QSYS QSYS RTVDOC RTVDSKINF QSYS QSYS QUSRSYS RUNQRY SAV SAVCFG QSYS QSYS QSYS QSYS QSYS SAVCHGOBJ QSYS QSYS QSYS SAVDLO QSYS QSYS QSYS SAVLIB QSYS QSYS QUSRSYS QSYS SAVOBJ QSYS QSYS QSYS SAVSAVFDTA QSYS

QPSRLDSP QSYSTAP QAOJRSTO QPRSTDLO QSYSTAP QASRRSTO QPSRLDSP QSYSTAP QPSRLDSP QSYSTAP QASRRSTO QPSRLDSP QSYSTAP QASRRSTO QSYSTAP QAOSIRTV QAEZDISK QAEZDISK QPQUPRFIL QSYSTAP QASAVOBJ QPSAVOBJ QSYSTAP QASAVOBJ QPSAVOBJ QSYSTAP QAOJSAVO QPSAVDLO QSYSTAP QASAVOBJ QPSAVOBJ QSRPNTWK QSYSTAP QASAVOBJ QPSAVOBJ QSYSTAP QASAVOBJ

PRTF TAPF PF PRTF TAPF PF PRTF TAPF PRTF TAPF PF PRTF TAPF PF TAPF PF PF PF PRTF TAPF PF PRTF TAPF PF PRTF TAPF PF PRTF TAPF PF PRTF PRTF TAPF PF PRTF TAPF PF

Restored objects status printer file. Tape device file used for input.

Model output file for restored document library objects. 2 Printer file for restored documents and folders. 1 Tape device file used for input. Model output file for libraries.
2 1

Restored objects status printer file. Tape device file used for input. Restored objects status printer file. Tape device file used for input.

Model output file for restored objects. Restored objects status printer file. Tape device file used for input. Model output file for user profiles. Tape device file used for input.
2 1

Retrieve document from document library output file. Model file for disk information. Database output file for disk information. Printer file used for query output. Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2 1

Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2

Tape device file used for output. Model output file for saved documents and folders. 2 Printer file for saved documents and folders. 1 Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2

Printer file for saved database file networks. Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2

Tape device file used for output. Model output file for saved objects.
2

152

System i: Programming Control language

QSYS QSYS SAVSECDTA QSYS QSYS QSYS SAVSYS QSYS QSYS QSYS SBMFNCJOB QSYS QUSRSYS QUSRSYS QUSRSYS SETTAPCGY QUSRSYS QUSRSYS SNDDSTQ SNDFNCIMG SNDPTFORD QUSRSYS QSYS QGPL QSYS SNDSRVRQS QGPL QSYS QUSRSYS STRCODE STRCPYSCN STRDFU user-lib QSYS QSYS QSYS QSYS QUSRSYS STRPDM CRTPFRDTA QPDA

QPSAVOBJ QSYSTAP QASAVOBJ QPSAVOBJ QSYSTAP QASAVOBJ QPSAVOBJ QSYSTAP QDFNDATA QFNDEVTBL QFNPGMTBL QFNUSRTBL QATACGY QLTACGY QASNADSQ QCRFDWNL Qnnnnnnn QESPRTF Qnnnnnnn QESPRTF QAEDCDBPF EVFCICFF QASCCPY QDFUPRT QPDZDTALOG QPDZDTAPRT QABBxxxxx QPUOPRTF

PRTF TAPF PF PRTF TAPF PF PRTF TAPF DSPF PF PF PF PF LF PF ICFF SAVF PRTF SAVF PRTF PF ICFF PF PRTF PRTF PRTF PF PRTF

Printer file for saved objects.

Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2

Tape device file used for output. Model output file for saved objects. Printer file for saved objects.
1 2

Tape device file used for output. Non-ICF finance display file. File containing data for device tables. File containing data for program tables. File containing data for user tables. Category database file. Category logical file. SNADS distribution queues table. ICF file used for communication with 4701 controller. PTF save file, where nnnnnnn is the PTF number. Printer file for PTF cover letters. PTF save file, where nnnnnnn is the PTF number. Printer file for PTF cover letters. File containing service contact data. ICF file used for communication with workstation. Pattern for copy screen output file. DFU printer file. DFU runtime audit log. DFU runtime printer data file. See Note E. Printer file for displayed lists in PDM.

All of the following files for the CRTPFRDTA command are physical files (PF) or logical files (LF) that are used as model files (not actual output files) to define the record formats of files created to store performance data collected by this command. All of these model files are in the QSYS library, and the files they create are in a library determined by the user (sets to the same library specified for the *MGTCOL object as the default- typically QPFRDATA). Each created file stores the specific type of performance data in the format defined for the specific type of data being collected. For the files listed as follows, the common part of each model files description begins here and the unique part of each description continues under the File usage column: QSYS QSYS QSYS QAPMAPPN QAPMASYN QAPMBSC PF PF PF ...APPN data.
2 2 2

...asynchronous data.

...binary synchronous data.

Control language

153

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QAPMJOBMI QAPMJOBOS QAPMJOBWT QAPMJOBWTD QAPMJSUM QAPMBUS QAPMCIOP QAPMCONF QAPMDDI QAPMDIOP QAPMDISK QAPMDOMINO QAPMECL QAPMETH QAPMFRLY QAPMHDLC QAPMHTTPB QAPMHTTPD QAPMIDLC QAPMJOBL QAPMLAPD QAPMLIOP QAPMMIOP QAPMPOOLB QAPMPOOLT QAPMPOOLL QAPMPPP QAPMRESP QAPMSAP

PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PF LF PF PF PF PF PF LF PF PF PF

...job data from MI. ...job data from the i5/OS operating system. ...Job wait bucket data.
2 2

...Job wait bucket descriptions. ...job data summarized. ...bus counter data.
2

...communications controller data. ...system configuration data.

2 2 2

...DDI distributed interface data. ...storage device controller data. ...disk storage (DASD) data. ...Domino data.
2 2 2

...ECL or token-ring LAN data. ...Ethernet statistics data. ...frame relay data.
2 2

...HDLC and SDLC control data.

...HTTP server (powered by Apache) base data. 2 ...HTTP server (powered by Apache) detail data. 2 ...ISDN data link control file entries data. ...logical view of job data from QAPMJOBMI and QAPMJOBOS. ...ISDN LAPD file entries data.
2 2 2 2

...local workstation controller (WSC) data. ...multifunction controller data. ...main storage pool data. ...pool tuning data.
2 2 2 2

...logical view as pool data. ...PPP protocol data.

2

...local workstation response data.

...token-ring LAN, Ethernet, Distributed Data Interface, and frame relay service access point. 2 ...subsystem description data. ...SNA data.
2 2 2 2 2 2

QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS QSYS

QAPMSBSD QAPMSNA QAPMSNADS QAPMSTND QAPMSTNE QAPMSTNL QAPMSTNY QAPMSYSCPU QAPMSYSL

PF PF PF PF PF PF PF PF LF

...SNADS data.

...DDI station data.

...Ethernet station data.

...token-ring LAN station data. ...frame relay station data. ...system CPU data.
2 2 2

...log view CPU sys data.

154

System i: Programming Control language

QSYS QSYS QSYS QSYS QSYS QSYS STRPRTEML STRPRTWTR STRQMQRY STRQST QSYS QSYS QSYS QQALIB QSYS QSYS QSYS QUSRSYS STRSDA STRSEU QGPL QGPL QPDA STRSST QSYS QTY QUSRSYS QTY QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS QUSRSYS TRCCNN
4

QAPMSYSTEM QAPMTCP QAPMTCPIFC QAPMTSK QAPMUSRTNS QAPMX25 QPEMPRTF QPSPLPRT QPQXPRTF QAQAxxxx00 QAQA00xxxx QAQA00xxxx QPQAPRT QABBxxxxx QDDSSRC QTXTSRC QPSUPRTF QPCSMPRT QATYALMF QATYSWTE QATYCDRF QATYSWTE QABBADMTB QABBCAN QABBCOX QABBDEX QABBDIC QABBDIX QABBDOX QABBFIX QABBIQTB QABBLADN QSYSPRT
4

PF PF PF PF PF PF PRTF PRTF PRTF PF LF PF PRTF PF PF PF PRTF PRTF PF PF PF PF PF PF PF PF PF PF PF PF PF PF PRTF

...system performance data. ...TCP system data.

2 2 2

...TCP interface data.

...system internal data.

...User defined transaction data . ...X.25 communications data. Emulation printer file.
2

Printer device file used for all printer writing. Printer file used by Query CPI.
2 2 1 2

Q & A supplied model database files. Q & A database model files. Q & A database model files. Q & A printer file. See Note F. DDS source default input file. SEU source default input file. SEU source member printer file. Service tools printer file.
1

Telephony database model file of alarm record formats. Telephony database file of user-created switch entries. Telephony database model file of alarm record formats. Telephony database file of user-created switch entries. ...administration table. ...candidates file. ...context index. ...external document index identifiers. ...dictionary. ...internal document index identifiers. ...document index table. ...fragment index. ...scheduling queue. ...list of indexed LADNs (library-assigned document names). Connection trace printer file.

QSYS

This QABBLADN file is not used by the STRRGZIDX and STRIDXMON commands. QSYS QSYS QACM0TRC QSYSPRT QAIFTRCF PF PRTF PF Trace CPI-Communications database model output file. 2 Trace CPI-Communications printer file. Trace ICF database output file.
Control language
1

TRCCPIC

TRCICF

QSYS

155

QSYS TRCINT QSYS QSYS TRCJOB QSYS QSYS UPDDTA QSYS QSYS VFYLNKLPDA WRKACTJOB WRKALR QSYS QSYS QUSRSYS QSYS WRKCFGSTS WRKCNTINF WRKDDMF WRKDEVTBL WRKDIR QSYS QUSRSYS QSYS QUSRSYS QSYS QSYS WRKDOCCVN QUSRSYS QUSRSYS QUSRSYS WRKDPCQ WRKDSKSTS WRKDSTL QSYS QSYS QSYS QSYS WRKDSTQ QSYS QUSRSYS WRKFCT WRKGRPPDM WRKHDWRSC WRKHTTPCFG WRKJOB WRKJOBQ WRKJOBSCDE WRKJRNA WRKLIBPDM WRKMBRPDM WRKMSG QRJE QPDA QSYS QUSRSYS QSYS QSYS QSYS QSYS QPDA QPDA QSYS

QPIFTRCF QPCSMPRT QSYSTAP QATRCJOB QPSRVTRC QPDZDTALOG QPDZDTAPRT QSYSPRT QPDSPAJB QAALERT QSYSPRT QSYSPRT QAEDCDBPF QPWRKDDM QFNDEVTBL QPDSPDDL QPDSPDSM QAO1CRL QAO1CVNP QAO1DCVN QPDXWRKD QPWCDSKS QPDSPLDL QPDSPLSM QPDSTSTS QASNADSQ QPDSPFCT QPUOPRTF QASUPTEL QATMHTTPC QPDSPJOB QPRTSPLQ QSYSPRT QPDSPJNA QPUOPRTF QPUOPRTF QPDSPMSG

PRTF PRTF TAPF PF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PF PRTF PF PRTF PRTF LF PF PRTF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PF PF PRTF PRTF PRTF PRTF PRTF PRTF PRTF

Trace ICF printer file.

Internal trace (for concurrent service monitor) printer file. Tape device file for output. Database file that defines the record format of the file created to store trace records. 2 Job trace printer output file. DFU runtime audit log. DFU runtime printer data file. Verify link supporting LPDA -2 printer file.
1 1

Active jobs display printer file. Alert database file. Alert printer file.
1

Configuration status printer file.

Database file containing contact data. Distributed data management (DDM) file attributes printer file. 1 File containing data for device tables. Directory entry details printer file. Directory entry summary printer file. Document conversion logical file for input or output. Document conversion physical file for input or output. Document conversion printer file. Printer file for DSNX/PC queued distribution requests. 1 Disk status printer file.
1

Distribution list details printer file. Distribution list summary printer file. Distribution status printer file.
1

SNADS destination queues table. Forms control table printer file.

1 1

Printer file for displayed lists in PDM.

Hardware resources locking database file. TCP/IP HTTP file. Job display printer file.
1 1

Job queue printer file (spooling queue). Job schedule entries printer file. Journal attributes printer file.
1 1 1 1

Printer file for displayed lists in PDM. Printer file for displayed lists in PDM.

Printer file for message queue messages.

156

System i: Programming Control language

WRKMSGD

QSYS

QPMSGD QATMSMTP QATMSMTPA QANFDNTF QPNFDNTF QANFNJE QPNFNJE QPDSPOLK QPUOPRTF QPRTSPLQ QPDSPSQD QPUOPRTF QFNPGMTBL

PRTF PF PF PF PRTF PF PRTF PRTF PRTF PRTF PRTF PRTF PF

Message description printer file. TCP/IP SMTP personal alias table. TCP/IP SMTP system alias table. Database file for display network files. Printer file for display network files. Database file for network job entries. Printer file for network job entries. Object locks display printer file.
1 1 1 1 1 1

WRKNAMSMTP QSYS QSYS WRKNETF QSYS QSYS WRKNETJOBE QUSRSYS QSYS WRKOBJLCK WRKOBJPDM WRKOUTQ WRKOUTQD WRKPARTPDM WRKPGMTBL WRKPRB QSYS QPDA QSYS QSYS QPDA QUSRSYS

Printer file for displayed lists in PDM. Output spooling queue printer file. Output queue description.
1 1

Printer file for displayed lists in PDM. File containing data for program tables.

All 8 of the QASXxxxx files shown in the QUSRSYS library for the WRKPRB command are the same subset of files that are shown in the QUSRSYS library for the DSPPRB command. QSYS QSYS QUSRSYS QSXPRTD QSXPRTL QASXxxxx QPUOPRTF QPQUPRFIL QPQAPRT QSYSPRT QPRTRDWT QPRJESTS QPRTRPYL QPDSPSBJ QPDSPSBS QPDSPSBJ QSYSPRT QAALSOC QPRTSPLF QPDSPSFA QSYSPRT QAEDSPI QANSSRI QPRTSSND QAITMON QAPTDDS QPDSPSTS QSYSPRT PRTF PRTF PF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PRTF PF PRTF PRTF PRTF PF PF PRTF PF PF PRTF PRTF Problem log detail printer file. Problem log summary printer file. See the DSPPRB command for these 8 files in the QUSRSYS library. Printer file for displayed lists in PDM. Printer file used for query output. Q & A printer file. Distributed relational database directory printer file. 1 Reader display printer file.
1 1 1

WRKPRJPDM WRKQRY WRKQST WRKRDBDIRE WRKRDR WRKRJESSN WRKRPYLE WRKSBMJOB WRKSBS WRKSBSJOB WRKSHRPOOL WRKSOC WRKSPLF WRKSPLFA WRKSPTPRD WRKSRVPVD WRKSRVRQS WRKSSND WRKSYSACT

QPDA QSYS QSYS QSYS QSYS QRJE QSYS QSYS QSYS QSYS QSYS QUSRSYS QSYS QSYS QSYS QUSRSYS QUSRSYS QRJE user-lib QPFR

Active status printer file for RJE session. System reply list printer file. Submitted jobs printer file.
1 1 1 1

Subsystem display printer file.

Subsystem jobs display printer file. Shared storage pools printer file. Sphere of control database file. Spooled file printer file.
1 1 1

Spooled file attributes printer file. Supported products printer file.

1

Service provider information file. Service requester file. Session description printer file.
1

Performance data collection file: job and Licensed Internal Code task data. 1 Performance data DDS source file. System status printer file. System values printer file.
1 1

WRKSYSSTS WRKSYSVAL

QSYS QSYS

Control language

157

WRKTAPCTG

QUSRSYS QUSRSYS QUSRSYS QUSRSYS QSYS

QATAMID QATAMID QATACGY QLTACGY QSYSTAP QATOCPTP QATOCMODEM QPTIRCV QSYSPRT QPDSPSBJ QFNUSRTBL QPRTRDWT

PF LF PF LF TAPF PF PF PRTF PRTF PRTF PF PRTF

Cartridge ID database file. Cartridge ID logical database file. Category database file. Category logical file. Tape device file for input. TCP/IP point-to-point profile configuration. TCP/IP point-to-point modem configuration. Printer file summary of files received. Printer file containing list of token-ring network adapters. 1 User jobs display printer file.
1 1

WRKTCPPTP

QUSRSYS QUSRSYS

WRKTIE WRKTRA WRKUSRJOB WRKUSRTBL WRKWTR

QSYS QSYS QSYS QUSRSYS QSYS

File containing data for user tables. Writer display printer file.

Related information Display Problems (DSPPRB) command

CL programming
To program using CL, you must understand the procedures and concepts specific to CL programming. A CL source program or CL procedure is a group of CL commands that tells the system where to get input, how to process it, and where to place the results. The program or procedure is assigned a name by which it can then be called by other procedures or bound into a program and called. As with other kinds of procedures, you must enter CL procedure source statements, compile, and bind them before you can run the procedure. When you enter CL commands individually (from the Command Entry display, for instance, or as individual commands in an input stream), each command is separately processed. When you enter CL commands as source statements for a CL procedure, the source remains for later modification if you choose, and the commands are compiled into a module. This module remains as a permanent system object that can be bound into other programs and run. Thus, CL is actually a high-level programming language for system functions. CL procedures ensure consistent processing of groups of commands. You can perform functions with a CL procedure that you cannot perform by entering commands individually, and the CL program or procedure provides better performance at run time than the processing of several separate commands. CL procedures can be used in batch or interactive processing. Certain commands or functions are restricted to either batch or interactive jobs. CL source statements consist of CL commands. You cannot use all CL commands as CL source statements, and you can use some of them only in CL procedures or original program model (OPM) programs. CL source statements can be entered in a database source member either interactively from a workstation or in a batch job input stream from a device. To create a program using CL source statements, you must enter the source statements into a database source member. You can then create an Integrated Language Environment (ILE) program by compiling the source member into a module and binding the module into a program object. CL procedures can be written for many purposes, including: v To control the sequence of processing and calling of other programs or procedures. v To display a menu and run commands based on options selected from that menu. This makes the workstation users job easier and reduces errors.

158

System i: Programming Control language

v To read a database file. v To handle error conditions issued from commands, programs or procedures, by monitoring for specific messages. v To control the operation of an application by establishing variables used in the application, such as date, time, and external indicators. v To provide predefined functions for the system operator, such as starting a subsystem or saving files. This reduces the number of commands the operator uses regularly, and it ensures that system operations are performed consistently. There are many advantages in using CL procedures for an application. For example: v Because the commands are stored in a form that can be processed when the program is created, using programs is faster than entering and running the commands individually. v CL procedures are flexible. Parameters can be passed to CL procedures to adapt the operations performed by the procedure to the requirements of a particular use. v CL procedures can be tested and debugged like other high-level language programs and procedures. v CL procedures and programs can incorporate conditional logic and special functions not available when commands are entered individually. v CL procedures can be bound with procedures of other languages. You cannot use CL procedures to: v Add or update records in database files. v Use printer or ICF files. v Use subfiles within display files. v Use program-described display files. Related tasks Using CL or other HLLs for mixed lists on page 283 When a command is run using CL or another high-level language (HLL), the elements in a mixed list are passed to the command processing program in this format.

Process for creating a CL source program or CL procedure

All programs are created in steps: source creation, module creation, and program creation. 1. Source creation. CL procedures consist of CL commands. In most cases, source statements are entered into a database file in the logical sequence determined by your application design. 2. Module creation. Using the Create Control Language Module (CRTCLMOD) command, this source is used to create a system object. The created CL module can be bound into programs. A CL module contains one CL procedure. Other high-level language (HLL) languages can contain multiple procedures for each module. 3. Program creation. Using the Create Program (CRTPGM) command, this module (along with other modules and service programs) is used to create a program. Note: If you want to create a program consisting of only one CL module, you can use the Create Bound CL Program (CRTBNDCL) command, which combines steps 2 and 3. If you want to create an original program model (OPM) CL program from the CL source statements, you can use the Create CL Program (CRTCLPGM) command. Related information Create Program (CRTPGM) command Create CL Program (CRTCLPGM) command Create Bound CL Program (CRTCLPGM) command

Control language

159

Interactive entry
Interactive entry allows you to enter commands individually. The i5/OS operating system provides many menus and displays to allow interactive entry, including the Programmer Menu, the Command Entry display, command prompt displays, and the Programming Development Manager (PDM) Menu. If you use the i5/OS security functions described in Security reference , your ability to use these displays is controlled by the authority given to you in your user profile. User profiles are generally created and maintained by a system security officer. A frequently used source entry method is the source entry utility (SEU), which is part of the WebSphere Development Studio. You can also use the Edit File (EDTF) command to enter or change CL commands in a database source file. However, EDTF does not provide the integrated CL command prompting support that is built into SEU. Related information Edit File (EDTF) command

Batch entry
You can create CL source, a CL module, and a program in one batch input stream. The following example shows the basic parts of the input stream. The input is submitted to a job queue using the Submit Job (SBMJOB) command. The input stream should follow this format:
// BCHJOB CRTBNDCL PGM(QGPL/EDUPGM) SRCFILE(PERLIST) // DATA FILE(PERLIST) FILETYPE(*SRC) . . (CL Procedure Source) . // /* // ENDINP

This stream creates a program from inline source. If you want to keep the source inline, a Copy File (CPYF) command could be used to copy the source into a database file. The program could then be created using the database file. You can also create a CL module directly from CL source on external media, such as tape, using an IBM-supplied device file. The IBM-supplied tape source file is QTAPSRC. Assume, for instance, that the CL source statements are in a source file on tape named PGMA. The first step is to identify the location of the source on tape by using the following override command with LABEL attribute override:
OVRTAPF FILE(QTAPSRC) LABEL(PGMA)

Now you can consider the QTAPSRC file as the source file on the Create CL Module (CRTCLMOD) command. To create the CL module based on the source input from the tape file, enter the following command:
CRTCLMOD MODULE(QGPL/PGMA) SRCFILE(QTAPSRC)

When the CRTCLMOD command is processed, it treats the QTAPSRC source file like any database source file. Using the override, the source is located on tape. PGMA is created in QGPL, and the source for that module remains on tape. Related information Submit Job (SBMJOB) command Copy File (CPYF) command

160

System i: Programming Control language

Create CL Module (CRTCLMOD) command

Parts of a CL procedure
While each source statement entered as part of a CL procedure is actually a CL command, the source can be divided into the basic parts that are used in many typical CL procedures. PGM command PGM PARM(&A) Optional PGM command beginning the procedure and identifying any parameters received. Declare commands (DCL, DCLF, COPYRIGHT, DCLPRCOPT) Mandatory declaration of procedure variables when variables are used, and optional definition of the size of the subroutine stack. The declare commands must precede all other commands except the PGM command. CL processing commands CHGVAR, SNDPGMMSG, OVRDBF, DLTF, ... CL commands used as source statements to manipulate constants or variables (this is a partial list). Logic control commands IF, THEN, ELSE, DO, ENDDO, DOWHILE, DOUNTIL, DOFOR, LEAVE, ITERATE, GOTO, SELECT, ENDSELECT, WHEN, OTHERWISE, CALLSUBR, SUBR, RTNSUBR, ENDSUBR Commands used to control processing within the CL procedure. | Built-in functions %SUBSTRING (%SST), %SWITCH, %BINARY (%BIN), %ADDRESS (%ADDR), %OFFSET (%OFS) Built-in functions and operators used in arithmetic, relational or logical expressions. Program control commands CALL, RETURN CL commands used to pass control to other programs. Procedure control commands CALLPRC, RETURN CL commands used to pass control to other procedures. ENDPGM command ENDPGM Optional End Program command. The sequence, combination, and extent of these components are determined by the logic and design of your application. A CL procedure can refer to other objects that must exist when the procedure is created, when the command is processed, or both. In some circumstances, for your procedure to run successfully, you might need: v A display file. Use display files to format information on a device display. If your procedure uses a display, you must enter and create the display file and record format by using the Create Display File (CRTDSPF) command before creating the module. You must declare it to the procedure in the declare section by using the Declare File (DCLF) command. v A database file. Records in a database file can be read by a CL procedure. If your procedure uses a database file, the file must be created using the Create Physical File (CRTPF) command or the Create Logical File (CRTLF) command before the module is created. You can use Data Description
Control language

161

Specifications (DDS), Structured Query Language (SQL), or interactive data definition utility (IDDU) to define the format of the records in the file. The file must also be declared to the procedure in the DCL section using the Declare File (DCLF) command. v Other programs. If you use a CALL command, the called program must exist before running the CALL command. It does not have to exist when compiling the calling module. v Other procedures. If you use the CALLPRC command, the called procedure must exist at the time CRTPGM is run. It does not have to exist when CRTCLMOD is run. Related tasks Accessing objects in CL programs on page 434 To access an object from a CL program, the object must be in the specified library when the command that refers to it runs. Working with files in CL procedures on page 438 Two types of files are supported in CL procedures and programs: display files and database files. Controlling flow and communicating between programs and procedures on page 227 The Call Program (CALL), Call Bound Procedure (CALLPRC), and Return (RETURN) commands pass control back and forth between programs and procedures. Related information Create Physical File (CRTPF) command Create Logical File (CRTLF) command Create Display File (CRTDSPF) command Declare File (DCLF) command Call Program (CALL) command Call Bound Procedure (CALLPRC) command

Example: Simple CL procedure

This example is a procedure that calls several programs. A CL program can be as simple or as complex as you want. To consolidate several activities normally done by the system operator at the beginning of the day (to call programs A, B, and C, for example), you can create a CL procedure STARTUP with the following code:
PGM /* STARTUP CALL PGM(A) CALL PGM(B) CALL PGM(C) ENDPGM */

In this example, the Programmer Menu is used to create the program. You could also use the programming development manager (PDM), which is part of the WebSphere Development Studio. To enter, create, and use this program, follow these steps.

162

System i: Programming Control language

To enter CL source, follow these steps: 1. Select option 8 (Edit source) on the Programmer Menu and specify STARTUP in the Parm field. (This option creates a source member named STARTUP that will also be the name of the program.) 2. Specify CLLE in the Type field and press the Enter key. 3. On the SEU display, use the I (insert) line command to enter the CL commands (CALL is a CL command).
Columns........: 1 71 Edit QGPL/QCLSRC Find......: _____________________________________________ STARTUP FMT A* .....A*. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ************** Beginning of data *********************************** ....... ....... ....... ....... ....... .......

When you have finished entering the source statements, complete these steps: 1. Press F3 to exit from SEU. 2. Accept the default on the exit display (option 2, Exit and update member) and press the Enter key to return to the Programmer Menu. 3. Select option 3 (Create object) to create a program from the source statements you entered. You do not have to change any other information on the display. Note: The referenced programs (A, B, and C) do not have to exist when the program STARTUP is created.

Control language

163

When the program is created, you can call it from the Programmer Menu by selecting option 4 (Call program) and specifying STARTUP in the Parm field. If you attempt to run this sample program, however, the referenced programs must exist by the time the CALL commands are run. Related information Call Program (CALL) command

Commands used in CL procedures

A CL procedure contains only CL commands. These can be IBM-supplied commands or commands defined by you. You cannot use some IBM-supplied commands in CL procedures. For information concerning the individual command descriptions and their applicability in CL procedures, see the information for a particular command using the CL command finder or the online help.

Commands entered on the RQSDTA and CMD parameters

Certain CL commands, such as Transfer Job (TFRJOB) and Submit Job (SBMJOB) have RQSDTA or CMD parameters that can use another CL command as the parameter value. Commands that can only be used within CL procedures cannot be used as values on the RQSDTA or CMD parameter. Related information Transfer Job (TFRJOB) command Submit Job (SBMJOB) command

Common commands used in CL procedures

The list contains the commands frequently used in CL procedures. You can use this list to select the appropriate command for the function you want.
System function Command
1

Command function Calling a program. Calling a procedure. Returning to the command following the command that caused a program or procedure to be run. Indicating the start of CL procedure source.
1

Change procedure Call (CALL) control Call Procedure (CALLPRC) Return (RETURN) CL procedure limits Program (PGM)
1

End Program (ENDPGM)

Indicating the end of CL procedure source.

164

System i: Programming Control language

System function CL procedure logic

Command If (IF)
1

Command function Processing commands based on the value of a logical expression.

1

Else (ELSE) Do (DO)

1

Defining the action to be taken for the else (false) condition of an IF command. Indicating the start of a Do group.
1

Do While (DOWHILE)

Indicating the start of a Do group that processes a set of commands while the value of a logical expression remains true. Indicating the start of a Do group that processes a set of commands until the value of a logical expression is true. Indicating the start of a Do group that processes commands zero or more times based on specified values. Ending processing of commands in a Do While, Do Until, or Do For group.

Do Until (DOUNTIL)1 Do For (DOFOR)1

Leave (LEAVE)

Iterate (ITERATE)

Ending processing of commands in a Do While, Do Until, or Do For group, and evaluates the group conditions again. Indicating the end of a Do group. Branching to another command. Indicating the start of a Select group, which allows conditional processing of command groups. Processing commands in a Select group when the value of a logical expression is true.
1

End Do (ENDDO) Go To (GOTO)

1 1

Select (SELECT) When (WHEN)1

Otherwise (OTHERWISE) End Select (ENDSELECT)

Defining the commands to be processed if no conditions on a When command in a Select group are true. Indicating the end of a Select group.
1

Call Subroutine (CALLSUBR) Subroutine (SUBR)1

Passing control to a subroutine defined within the same procedure. Delimiting the group of commands which define a subroutine. Exiting a subroutine. Ending a subroutine. Changing the value of a CL variable. Declaring a variable.

Return Subroutine (RTNSUBR)1 End Subroutine (ENDSUBR) CL procedure variables Conversion Change Variable (CHGVAR) Declare (DCL)
1 1 1 1

Change Variable (CHGVAR) Convert Date (CVTDAT)

1

Changing the value of a CL variable. Changing the format of a date. Changing a data area. Creating a data area. Deleting a data area. Displaying a data area.
1

Data areas

Change Data Area (CHGDTAARA) Create Data Area (CRTDTAARA) Delete Data Area (DLTDTAARA) Display Data Area (DSPDTAARA) Retrieve Data Area (RTVDTAARA)

Copying the content of a data area to a CL variable.

Control language

165

System function Files

Command End Receive (ENDRCV) Declare File (DCLF) Receive File (RCVF)
1 1 1

Command function Canceling a request for input previously issued by a RCVF, SNDF, or SNDRCVF command to a display file. Declaring a display or database file. Reading a record from a display or database file. Retrieving a description of a specific member of a database file. Writing a record to a display file.
1

Retrieve Member Description (RTVMBRD) 1 Send File (SNDF)

1

Send/Receive File (SNDRCVF) Wait (WAIT) Messages

1

Writing a record to a display file and reads that record after the user has replied. Waiting for data to be received from an SNDF, RCVF, or SNDRCVF command issued to a display file.

Monitor Message (MONMSG) Receive Message (RCVMSG)

1

Monitoring for escape, status, and notify messages sent to a programs message queue. Copying a message from a message queue into CL variables in a CL procedure.

Remove Message (RMVMSG) Retrieve Message (RTVMSG) Send Program Message (SNDPGMMSG) 1 Send Reply (SNDRPY)
1 1

Removing a specified message from a specified message queue. Copying a predefined message from a message file into CL procedure variables. Sending a program message to a message queue. Sending a reply message to the sender of an inquiry message. Sending an informational or inquiry message to a display station or system operator. Checking for the existence of an object and, optionally, the necessary authority to use the object. Producing a cross-reference listing for a specified group of commands used in a specified group of CL procedures. Generating CL command source for creating existing configuration objects and placing the source in a source file member. Giving applications the capability to retrieve configuration status from three configuration objects: line, controller, and device.
1

Send User Message (SNDUSRMSG) Miscellaneous commands Check Object (CHKOBJ) Print Command Usage (PRTCMDUSG) Retrieve Configuration Source (RTVCFGSRC) Retrieve Configuration Status (RTVCFGSTS) 1 Retrieve Job Attributes (RTVJOBA)

Retrieving the value of one or more job attributes and placing the values in a CL variable. Retrieving a system value and placing it into a CL variable. Retrieving user profile attributes and placing them into CL variables.

Retrieve System Value (RTVSYSVAL)

1

Retrieve User Profile (RTVUSRPRF)

166

System i: Programming Control language

System function Program creation commands

Command Create CL Module (CRTCLMOD) Delete Module (DLTMOD) Delete Program (DLTPGM) Create Bound Control Language Program (CRTBNDCL) Create CL Program (CRTCLPGM) Create Program (CRTPGM) Create Service Program (CRTSRVPGM)

Command function Creating a CL module. Deleting a module. Deleting a program. Creating a bound CL program. Creating an original program model (OPM) CL program. Creating a program from one or more modules. Creating a service program from one or more modules.

Indicates the commands that you can use only in CL programs and procedures.

Related information CL command finder

Operations performed by CL procedures

This is an overview of the types of operations that can be performed by using CL procedures. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. In general, you can perform the following operations: v Use variables, logic control commands, expressions, and built-in functions to manipulate and process data within a CL procedure:
PGM DCL &C *LGL DCL &A *DEC VALUE(22) DCL &B *CHAR VALUE(ABCDE) CHGVAR &A (&A + 30) IF (&A < 50) THEN(CHGVAR &C 1) DSPLIB (Q &B) IF (%SST(&B 5 1)=E) THEN(CHGVAR &A 12) ENDPGM

v Use a system value as a variable in a CL procedure.

Control language

167

v Use a job attribute as a variable in a CL procedure.

v Send and receive data to and from a display file with a CL procedure.

v Create a CL procedure to monitor error messages for a job, and take corrective action if necessary.

168

System i: Programming Control language

PGM MONMSG MSGID(CPF0001) EXEC(GOTO ERROR) CALL PROGA CALL PROGB RETURN ERROR: SNDPGMMSG MSG(A CALL command failed) MSGTYPE(*ESCAPE) ENDPGM

v Control processing among procedures and programs and pass parameters from a CL procedure to other procedures or programs to override files.

Control language

169

Used as a controlling procedure, a CL procedure can call procedures written in other languages. The preceding illustration shows how control can be passed between a CL procedure and RPG IV* and Integrated Language Environment (ILE) COBOL procedures in an application. To use the application, a workstation user would request program A, which controls the entire application. The illustration shows a single bound program (PGMA) that is called using the CALL command with PGMA. PGMA consists of: v A CL procedure (PGMA) calling an RPG IV procedure (PGMB) v An RPG IV procedure (PGMB) calling another RPG IV procedure (PGMC)

170

System i: Programming Control language

v An RPG IV procedure (PGMB) calling a CL procedure (PGMD) v A CL procedure (PGMA) calling an ILE COBOL procedure (PGME) v An ILE COBOL procedure (PGME) calling a CL procedure (PGMF)

The procedures can be created as indicated in the following example. You can enter source for procedures in separate source members.
CRTCLMOD PGMA CRTRPGMOD PGMB CRTRPGMOD PGMC CRTCLMOD PGMD CRTCBLMOD PGME CRTCLMOD PGMF CRTPGM PGM(PGMA) + MODULE(PGMA PGMB PGMC PGMD PGME PGMF) + ENTMOD(*FIRST)

Variables in CL commands
CL procedures consist of CL commands. Each command consists of the command name, parameter keyword names, and parameter values. Parameter values can be expressed as variables, constants, or expressions. A variable is a named changeable value that can be accessed or changed by referring to its name. Variables can be used as substitutes for most parameter values on CL commands. When a CL variable is specified as a parameter value and the command containing it is run, the value of the variable is used as the parameter value. Every time the command is run, a different value can be substituted for the variable. Variables and expressions can be used as parameter values only in CL procedures and programs. Variables are not stored in libraries; they are not objects; and their values are destroyed when the procedure that contains them is no longer active. The use of variables as values gives CL programming a
Control language

171

special flexibility, because this allows high-level manipulation of objects whose content may change by specific applications. You might, for instance, write a CL procedure to direct the processing of other programs or the operation of several workstations without specifying which programs or workstations are to be controlled. The system identifies these as variables in the CL procedure. You can define (specify) the value of the variables when running the CL procedure. In addition to the uses discussed in this section, variables can be used to: v Pass information between procedures and jobs. v Pass information between procedures and device displays. v Conditionally process commands. v Create objects. A variable can be used in place of an object name or library name, or both. The following example shows the Create Physical File (CRTPF) command used with a specified library in the first line, and with a variable replacing the library name in the second line:
CRTPF CRTPF FILE(DSTPRODLB/&FILE) FILE(&LIB/&FILE)

Variables cannot be used to change a command name or keyword or to specify a procedure name for the CALLPRC command. Command parameters, however, can be changed during the processing of a CL procedure through the use of the prompting function. It is also possible to assemble the keywords and parameters for a command and process it using the QCAPCMD API or QCMDEXC API. Related tasks Controlling flow and communicating between programs and procedures on page 227 The Call Program (CALL), Call Bound Procedure (CALLPRC), and Return (RETURN) commands pass control back and forth between programs and procedures. Working with multiple device display files on page 447 A multiple device display configuration occurs when a single job called by one requester communicates with multiple display stations through one display file. While only one display file can be handled by a CL procedure, the display file, or different record formats within it, can be sent to several device displays. Prompting for user input at run time on page 334 With most CL procedures and programs, the workstation user provides input to the procedure or program by specifying command parameter values passed to the procedure or program or by typing into input-capable fields on a display prompt. QCAPCMD program on page 329 The Process Commands (QCAPCMD) API performs command analyzer processing on command strings. QCMDEXC program on page 329 The Execute Command (QCMDEXC) API is an IBM-supplied program that runs a single command. Data type errors using the CALL command on page 236 When you use the Call Program (CALL) command, data type errors might occur. Related reference Controlling processing within a CL program or CL procedure on page 181 You can use commands to change the flow of logic within your CL procedure.

Declaring variables to a CL procedure

All variables must be declared (defined) to the CL procedure before they can be used by the procedure. There are two ways of declaring variables: v Declare variable. Defining it is accomplished using the Declare CL Variable (DCL) command and consists of defining the attributes of the variable. These attributes include type, length, and initial value.

172

System i: Programming Control language

DCL

VAR(&AREA)

TYPE(*CHAR)

LEN(4)

VALUE(BOOK)

v Declare file. If your CL procedure uses a file, you must specify the name of the file in the FILE parameter on the Declare File (DCLF) command. The file contains a description (format) of the records in the file and the fields in the records. During compilation, the DCLF command implicitly declares CL variables for the fields and indicators defined in the file. For example, if the DDS for the file has one record in it with two fields (F1 and F2), then two variables, &F1 and &F2, are automatically declared in the program.
DCLF FILE(MCGANN/GUIDE)

If the file is a physical file which was created without DDS, one variable is declared for the entire record. The variable has the same name as the file, and its length is the same as the record length of the file. The declare commands must precede all other commands in the procedure (except the PGM command), but they can be intermixed in any order.

Rules for using the Declare CL Variable command

In its simplest form, the Declare CL Variable (DCL) command has the following parameters.

When you use a DCL command, you must use the following rules: v The CL variable name must begin with an ampersand (&) followed by as many as 10 characters. The first character following the & must be alphabetic and the remaining characters alphanumeric. For example, &PART. v The CL variable value must be one of the following: A character string as long as 5000 characters. A packed decimal value totaling up to 15 digits with as many as 9 decimal positions. A logical value 0 or 1, where 0 can mean off, false, or no, and 1 can mean on, true, or yes. A logical variable must be either 0 or 1. An integer value of two bytes or four bytes. The value can be negative if *INT is specified for the TYPE parameter. | A pointer value which can hold the location of data in storage. v If you do not specify an initial value, the following is assumed: 0 for decimal variables. Blanks for character variables. 0 for logical variables. 0 for integer variables. Null for pointer variables. | For decimal and character types, if you specify an initial value and do not specify the LEN parameter, the default length is the same as the length of the initial value. For type *CHAR, if you do not specify the LEN parameter, the string can be as long as 5000 characters. For type *INT or *UINT, if you do not specify the LEN parameter, the default length is 4. v Declare the parameters as variables in the program DCL statements. Related information Declare CL Variable (DCL) command
Control language

173

| Uses for based variables | Based variables can be used to map variables passed to the program or manipulate arrays of values. | The basing pointer must be set using the ADDRESS keyword on the Declare (DCL Command) or with | the %ADDRESS built-in function before being used. After the basing pointer is set, the variables will | work like local variables. | | | | | | | | | | | | | | | | | | | In the following example, the basing pointer &PTR is declared to be equal to the address of &AUTO. The variable &BASED then has the value of the first 10 bytes addressed by the pointer variable &PTR. Later in the procedure, the value of variable &BASED is checked for equality against the first 10 bytes of variable &AUTO. If the values are the same, meaning pointer &PTR addresses the first byte of &AUTO, the pointer offset is changed to address byte 11 of variable &AUTO. Now variable &BASED has a value equal to bytes 11-20 of variable &AUTO. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL &AUTO *CHAR 20 DCL &PTR *PTR ADDRESS(&AUTO) DCL &BASED *CHAR 10 STG(*BASED) BASPTR(&PTR) : IF COND(%SST(&AUTO 1 10) *EQ &BASED) + THEN(CHGVAR %OFS(&PTR) (%OFS(&PTR) + 10)) : ENDPGM

Related information Declare CL Variable (DCL) command

| Uses for defined variables | Defined variables make it easy to manage complex data structures in control language (CL) by | eliminating the need to substring values out of a large variable. | Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. | | Defined variables can be used to map different parts of the defined on variable or the same part of a | given variable in different ways. | | | | | | | | | | | | | In the following example, the variables &LIBNAME will always be equal to the first 10 bytes of &OBJECT. Using the defined variable &LIBNAME will improves the readability of the code and makes it easier to work with. The variable &OBJECT provides the storage for the &LIBNAME and &OBJNAME variables.
PGM DCL &OBJECT *CHAR 20 DCL &LIBNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT) DCL &OBJNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT 11) : IF COND(%SST(&OBJECT 11 10) *EQ &OBJNAME) + THEN(...)) : ENDPGM

| You can also make the same storage with multiple definitions. In this example, the variables &BINLEN | and &CHARLEN both refer to the same 4 bytes of variable &STRUCT. The program can then use the | definition that best suits its requirements.

174

System i: Programming Control language

| | | | | | | | | | | | | | | | | | | | | | | | | | | | |

PGM DCL &STRUCT *CHAR 50 DCL &BINLEN *INT 4 STG(*DEFINED) DEFVAR(&STRUCT) DCL &CHARLEN *CHAR 4 STG(*DEFINED) DEFVAR(&STRUCT) : ENDPGM

This example shows how a defined variable can be used to change values in a variable. This example also makes use of the %OFFSET built-in function and a based variable to navigate the library list. This is not the optimal way to do message substation but illustrates some of the capabilities of defined variables.
PGM DCL &MESSAGE *CHAR 25 VALUE(LIBRARY NNN IS XXXXXXXXXX) DCL &SEQUENCE *CHAR 3 STG(*DEFINED) DEFVAR(&MESSAGE 9) DCL &MSGLIBN *CHAR 10 STG(*DEFINED) DEFVAR(&MESSAGE 16) DCL &COUNTER *INT 2 DCL &LIBL *CHAR 165 DCL &PTR *PTR ADDRESS(&LIBL) DCL &LIBLNAME *CHAR 10 STG(*BASED) BASPTR(&PTR) : RTVJOBA SYSLIBL(&LIBL) CHGVAR &COUNTER 0 DOFOR &COUNTER FROM(1) TO(15) IF (&LIBLNAME *EQ ) THEN(LEAVE) CHGVAR &SEQUENCE &COUNTER CHGVAR &MSGLIBN &LIBLNAME SNDPGMMSG MSGID(CPF9898) MSGF(QSYS/QCPFMSG) MSGDTA(&MESSAGE) CHGVAR %OFS(&PTR) (%OFS(&PTR) + 11) ENDDO : ENDPGM

| Variables to use for specifying a list or qualified name Variables can be used to specify a list or qualified name. The value on a parameter can be a list. For example, the Change Library List (CHGLIBL) command requires a list of libraries on the LIBL parameter, each separated by blanks. The elements in this list can be variables:
CHGLIBL LIBL(&LIB1 &LIB2 &LIB3)

When variables are used to specify elements in a list, each element must be declared separately:
DCL VAR(&LIB1) TYPE(*CHAR) LEN(10) VALUE(QTEMP) DCL VAR(&LIB2) TYPE(*CHAR) LEN(10) VALUE(QGPL) DCL VAR(&LIB3) TYPE(*CHAR) LEN(10) VALUE(DISTLIB) CHGLIBL LIBL(&LIB1 &LIB2 &LIB3)

Variable elements cannot be specified in a list as a character string. Incorrect:

DCL VAR(&LIBS) TYPE(*CHAR) LEN(20) + VALUE(QTEMP QGPL DISTLIB) CHGLIBL LIBL(&LIBS)

When presented as a single character string, the system does not view the list as a list of separate elements, and an error will occur. You can also use variables to specify a qualified name, if each qualifier is declared as a separate variable.
DCL VAR(&PGM) TYPE(*CHAR) LEN(10) DCL VAR(&LIB) TYPE(*CHAR) LEN(10) CHGVAR VAR(&PGM) VALUE(MYPGM) CHGVAR VAR(&LIB) VALUE(MYLIB) .
Control language

175

. . DLTPGM PGM(&LIB/&PGM) ENDPGM

In this example, the program and library name are declared separately. The program and library name cannot be specified in one variable, as in the following example. Incorrect:
DCL VAR(&PGM) TYPE(*CHAR) LEN(11) CHGVAR VAR(&PGM) VALUE(MYLIB/MYPGM) DLTPGM PGM(&PGM)

Here again the value is viewed by the system as a single character string, not as two objects (a library and an object). If a qualified name must be handled as a single variable with a character string value, you can use the built-in function %SUBSTRING and the *TCAT concatenation function to assign object and library names to separate variables. Related tasks Defining commands on page 258 CL commands enable you to request a broad range of functions. You can use IBM-supplied commands, change the default values for command parameters, and define your own commands. Related reference %SUBSTRING built-in function on page 205 The substring built-in function (%SUBSTRING or%SST) produces a character string that is a subset of an existing character string and can only be used within a CL procedure.

Cases of characters in variables

There are restrictions on the cases used for characters in variables. Reserved values, such as *LIBL, that can be used as variables must always be expressed in uppercase letters, especially if they are presented as character strings enclosed in single quotation marks. For instance, if you wanted to substitute a variable for a library name on a command, the correct code is as follows:
DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE(*LIBL) DLTPGM &LIB/MYPROG;

However, it would be incorrect to specify the VALUE parameter this way:

DCL VAR(&LIB) TYPE(*CHAR) LEN(10) VALUE(*libl)

Note that if this VALUE parameter had not been enclosed in single quotation marks, it would have been correct, because without the single quotation marks it would be translated to uppercase automatically. This error frequently occurs when the parameter is passed as input to a procedure or program from a display as a character string, and the display entry is made in lowercase. Note: The previous paragraph does not take into account the fact that conversion to uppercase is language dependent. Remember to rely on the system to convert values to uppercase can produce unexpected results.

Variables that replace reserved or numeric parameter values

Character variables can be used for some commands to represent a value on the command parameter. Some CL commands allow both numeric or predefined (reserved) values on certain parameters. Where this is true, you can also use character variables to represent the value on the command parameter. Each parameter on a command can accept only certain types of values. The parameter can allow an integer, a character string, a reserved value, a variable of a specified type, or some mixture of these, as

176

System i: Programming Control language

values. Some types of values are required for parameters. If the parameter allows numeric values (if the value is defined in the command as *INT2, *INT4, *UINT2, *UINT4, or *DEC) and also allows reserved values (a character string preceded by an asterisk), you can use a variable as the value for the parameter. The variable must be declared as TYPE(*CHAR) if you intend to use a reserved value. For example, the Change Output Queue (CHGOUTQ) command has a job separator (JOBSEP) parameter that can have a value of either a number (0 through 9) or the predefined default, *SAME. Because both the number and the predefined value are acceptable, you can also write a CL procedure that substitutes a character variable for the JOBSEP value. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL &NRESP *CHAR LEN(6) DCL &SEP *CHAR LEN(4) DCL &FILNAM *CHAR LEN(10) DCL &FILLIB *CHAR LEN(10) DCLF..... . . . LOOP: SNDRCVF..... IF (&SEP *EQ IGNR) GOTO END ELSE IF (&SEP *EQ NONE) CHGVAR &NRESP 0 ELSE IF (&SEP *EQ NORM) CHGVAR &NRESP 1 ELSE IF (&SEP *EQ SAME) CHGVAR &NRESP *SAME CHGOUTQ OUTQ(&FILLIB/&FILNAM) JOBSEP(&NRESP) GOTO LOOP END: RETURN ENDPGM

In the preceding example, the display station user enters information on a display describing the number of job separators required for a specified output queue. The variable &NRESP is a character variable manipulating numeric and predefined values (note the use of single quotation marks). The JOBSEP parameter on the Change Output Queue (CHGOUTQ) command will recognize these values as if they had been entered as numeric or predefined values. The DDS for the display file used in this program should use the VALUES keyword to restrict the user responses to IGNR, NONE, NORM, or SAME. If the parameter allows a numeric type of value (*INT2, *INT4, *UINT2, *UINT4, or *DEC) and you do not intend to enter any reserved values (such as *SAME), then you can use a decimal or integer variable in that parameter. Another alternative for this function is to use the prompter within CL procedures. Related tasks Defining commands on page 258 CL commands enable you to request a broad range of functions. You can use IBM-supplied commands, change the default values for command parameters, and define your own commands.

Changing the value of a variable

You can change the value of a CL variable using the Change Variable (CHGVAR) command. The value can be changed: v To a constant, shown in this example:
CHGVAR VAR(&INVCMPLT) VALUE(0)

&INVCMPLT is set to 0. You could also use this notation:

CHGVAR &INVCMPLT 0
Control language

177

v To the value of another variable, shown in this example:

CHGVAR VAR(&A) VALUE(&B)

&A is set to the value of the variable &B You could also use this notation:
CHGVAR CHGVAR &A &B VALUE(&A + 1)

v To the value of an expression after it is evaluated, shown in the following example:

VAR(&A)

The value of &A is increased by 1. You could also use this notation:
CHGVAR CHGVAR &A (&A + 1) VALUE(%SST(&B 1 5))

v To the value produced by the built-in function %SST, shown in the following example:
VAR(&A)

&A is set to the first five characters of the value of the variable &B v To the value produced by the built-in function %SWITCH, shown in the following example:
CHGVAR VAR(&A) VALUE(%SWITCH(0XX111X0))

&A is set to 1 if job switches 1 and 8 are 0 and job switches 4, 5 and 6 are 1; otherwise, &A is set to 0. v To the value produced by the built-in function %BIN:
CHGVAR VAR(&A) VALUE(%BIN((%B 1 4))

The first four characters of variable &B are converted to the decimal equivalent and stored in variable &A. The CHGVAR command can be used to retrieve and to change the local data area also. For example, the following commands blank out 10 bytes of the local data area and retrieve part of the local data area:
CHGVAR %SST(*LDA 1 10) CHGVAR &A %SST(*LDA 1 10)

The following table shows valid assignments to variables from values (literals or variables).
Table 23. Valid assignments to variables from values Logical value Logical variable Character variable Decimal variable Signed integer variable Unsigned integer variable X X X X X X X X X X X X X X X X X X Character value Decimal value Signed integer value Unsigned integer value

Notes: 1. When specifying a numeric value for a character variable, remember the following: v The value of the character variable is right-aligned and, if necessary, padded with leading zeros. v The character variable must be long enough to contain a decimal point and a minus (-) sign, when necessary. v When used, a minus (-) sign is placed in the leftmost position of the value.

178

System i: Programming Control language

For example, &A is a character variable to be changed to the value of the decimal variable &B. The length of &A is 6. The length of &B is 5 and decimal positions is 2. The current value of &B is 123. The resulting value of &A is 123.00. 2. When specifying a character value for a numeric variable, remember the following: v The decimal point is determined by the placement of a decimal point in the character value. If the character value does not contain a decimal point, the decimal point is placed in the rightmost position of the value. v The character value can contain a minus (-) sign or plus (+) sign immediately to the left of the value; no intervening blanks are allowed. If the character value has no sign, the value is assumed to be positive. v If the character value contains more digits to the right of the decimal point than can be contained in the numeric variable, the digits are truncated if it is a decimal variable, or rounded if it is an integer variable. If the excess digits are to the left of the decimal point, they are not truncated and an error occurs. For example, &C is a decimal variable to be changed to the value of the character variable &D. The length of &C is 5 with 2 decimal positions. The length of &D is 10 and its current value is +123.1bbbb (where b=blank). The resulting value of &C is 123.10. Related reference %ADDRESS built-in function in a CL program or procedure on page 201 The address built-in function (%ADDRESS or %ADDR) can be used to change or test the memory address stored in a CL pointer variable and can only be used within a CL procedure. %OFFSET built-in function on page 204 The offset built-in function (%OFFSET or %OFS) can be used to store or change the offset portion of a CL pointer variable and can only be used within a CL procedure. %SUBSTRING built-in function on page 205 The substring built-in function (%SUBSTRING or%SST) produces a character string that is a subset of an existing character string and can only be used within a CL procedure. %SWITCH built-in function on page 207 The switch built-in function (%SWITCH) compares one or more of eight switches with the eight switch settings already established for the job and returns a logical value of 0 or 1. %BINARY built-in function on page 202 The binary built-in function (%BINARY or %BIN) interprets the contents of a specified CL character variable as a signed binary integer. Related information Change Variable (CHGVAR) command

Trailing blanks on command parameters

In certain command parameters, you can define how trailing blanks are processed. Some command parameters are defined with the parameter value of VARY(*YES). This parameter value causes the length of the value passed to be the number of characters between the single quotation marks. When a CL variable is used to specify the value for a parameter defined in this way, the system removes trailing blanks before determining the length of the variable to be passed to the command processor program. If the trailing blanks are present and are significant for the parameter, you must take special actions to ensure that the length passed includes them. Most command parameters are defined and used in ways that do not cause this condition to occur. An example of a parameter defined where this condition is likely to occur is the key value element of the POSITION parameter on the Override with Database File (OVRDBF) command. When this condition occurs, the result that you want can be attained for these parameters by constructing a command string that delimits the parameter value with single quotation marks and passing the string to QCMDEXC or QCAPCMD for processing.

Control language

179

Here is an example of a program that can be used to run the Override with Database File (OVRDBF) command so that the trailing blanks are included as part of the key value. This same technique can be used for other commands that have parameters defined using the parameter VARY(*YES); trailing blanks must be passed with the parameter. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
/* /* /* /* /* /* /* /* /* /* /* /* /* PGM PARM(&KEYVAL &LEN) PROGRAM TO SHOW HOW TO SPECIFY A KEY VALUE WITH TRAILING */ BLANKS AS PART OF THE POSITION PARAMETER ON THE OVRDBF */ COMMAND IN A CL PROGRAM. */ THE KEY VALUE ELEMENT OF THE POSITION PARAMETER OF THE OVRDBF */ COMMAND IS DEFINED USING THE VARY(*YES) PARAMETER. */ THE DESCRIPTION OF THIS PARAMETER ON THE ELEM COMMAND */ DEFINITION STATEMENT SPECIFIES THAT IF A PARAMETER */ DEFINED IN THIS WAY IS SPECIFIED AS A CL VARIABLE THE */ LENGTH IS PASSED AS THE VARIABLE WITH TRAILING BLANKS */ REMOVED. A CALL TO QCMDEXC USING APOSTROPHES TO DELIMIT */ THE LENGTH OF THE KEY VALUE CAN BE USED TO CIRCUMVENT */ THIS ACTION. */ PARAMETERS-*/ DCL VAR(&KEYVAL) TYPE(*CHAR) LEN(32) /* THE VALUE + OF THE REQUESTED KEY. NOTE IT IS DEFINED AS + 32 CHAR. */ DCL VAR(&LEN) TYPE(*INT) /* THE LENGTH + OF THE KEY VALUE TO BE USED. ANY VALUE OF + 1 TO 32 CAN BE USED */ THE STRING TO BE FINISHED FOR THE OVERRIDE COMMAND TO BE */ PASSED TO QCMDEXC (NOTE 2 APOSTROPHES TO GET ONE). */ DCL VAR(&STRING) TYPE(*CHAR) LEN(100) + VALUE(OVRDBF FILE(X3) POSITION(*KEY 1 FMT1 ) POSITION MARKER 123456789 123456789 123456789 123456789 */ DCL VAR(&END) TYPE(*DEC) LEN(15 5) /* A VARIABLE + TO CALCULATE THE END OF THE KEY IN &STRING */ CHGVAR CHGVAR CHGVAR CALL ENDPGM VAR(%SST(&STRING 40 &LEN)) VALUE(&KEYVAL) /* + PUT THE KEY VALUE INTO COMMAND STRING FOR + QCMDEXC IMMEDIATELY AFTER THE APOSTROPHE. */ VAR(&END) VALUE(&LEN + 40) /* POSITION AFTER + LAST CHARACTER OF KEY VALUE */ VAR(%SST(&STRING &END 2)) VALUE()) /* PUT + A CLOSING APOSTROPHE & PAREN TO END + PARAMETER */ PGM(QCMDEXC) PARM(&STRING 100) /* CALL TO + PROCESS THE COMMAND */

/* /* /*

Note: If you use VARY(*YES) and RTNVAL(*YES) and are passing a CL variable, the length of the variable is passed rather than the length of the data in the CL variable. Related information Override with Data Base File (OVRDBF) command

Writing comments in CL procedures

To write comments in your CL procedures or add comments to commands in your procedures, use the character pairs /* and */. The comment is written between these symbols. The starting comment delimiter, /*, requires three characters unless the /* characters appear in the first two positions of the command string. In the latter situation, /* can be used without a following blank before a command. You can enter the three-character starting comment delimiters in any of the following ways (b represents a blank):

180

System i: Programming Control language

/*b b/* /**

Therefore, the starting comment delimiter can be entered in different ways. The starting comment delimiter, /*, can: v Begin in the first position of the command string v Be preceded by a blank v Be followed by a blank v Be followed by an asterisk (/**) Note: A comment cannot be embedded within a comment. For example, in the following procedure, comments are written to describe possible user responses to a set of menu options. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM /* ORD040C ORDER DEPT GENERAL MENU */ DCLF FILE(ORD040CD) START: SNDRCVF RCDFMT(MENU) SELECT WHEN (&RESP=1) THEN(CALL CUS210) /* CUSTOMER INQUIRY WHEN (&RESP=2) THEN(CALL ITM210) /* ITEM INQUIRY WHEN (&RESP=3) THEN(CALL CUS210) /* CUSTOMER NAME SEARCH WHEN (&RESP=4) THEN(CALL ORD215) /* ORDERS BY CUST WHEN (&RESP=5) THEN(CALL ORD220) /* EXISTING ORDER WHEN (&RESP=6) THEN(CALL ORD410C) /* ORDER ENTRY WHEN (&RESP=7) THEN(RETURN) ENDSELECT GOTO START ENDPGM

*/ */ */ */ */ */

Controlling processing within a CL program or CL procedure

You can use commands to change the flow of logic within your CL procedure. Commands in a CL procedure are processed in consecutive sequence. Each command is processed, one after another, in the sequence in which it is encountered. You can alter this consecutive processing using commands that change the flow of logic in the procedure. These commands can be conditional or unconditional. Unconditional branching means that you can instruct processing to branch to commands or sets of commands located anywhere in the procedure without regard to what conditions exist at the time the branch instruction is processed. Unconditional processing commands include: v GOTO v ITERATE v LEAVE v CALLSUBR Conditional branching means that under certain specified conditions, processing can branch to sections or commands that are not consecutive within the procedure. The branching can be to any statement in the procedure. This is called conditional processing because the branching only occurs when the specified condition is true. Conditional processing is typically associated with the IF command. With the ELSE command, you can specify alternative processing if the condition is not [Link] simple DO command

Control language

181

allows you to create groups of commands that are always processed together, as a group, under specified conditions. Conditional processing commands include: v IF and THEN v SELECT, WHEN, and OTHERWISE v DOFOR v DOWHILE v DOUNTIL Related tasks Variables in CL commands on page 171 CL procedures consist of CL commands. Each command consists of the command name, parameter keyword names, and parameter values. Related information CL command finder

GOTO command and command labels in a CL program or procedure

The Go To (GOTO) command processes an unconditional branch. With the GOTO command, processing is directed to another part (identified by a label) of the procedure whenever the GOTO command is encountered. This branching does not depend on the evaluation of an expression. After the branch to the labeled statement, processing begins at that statement and continues in consecutive sequence; it does not return to the GOTO command unless specifically directed back by another instruction. You can branch forward or backward. You cannot use GOTO to go to a label outside the procedure, nor can you use a GOTO to branch into or out of a subroutine defined within the procedure. The GOTO command has one parameter, which contains the label of the statement branched to:
GOTO CMDLBL(label)

A label identifies the statement in the procedure to which processing is directed by the GOTO command. To use a GOTO command, the command you are branching to must have a label. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM . . . SNDRCVF RCDFMT(MENU) IF (&RESP=1) THEN(CALL CUS210) . . . GOTO START . . . ENDPGM

START:

The label in this example is START. A label can have as many as 10 characters and must be immediately followed by a colon, but blanks can occur between the label and the command name. Related information CL command finder Go To (GOTO) command

182

System i: Programming Control language

IF command in a CL program or procedure

The If (IF) command is used to state a condition that, if true, specifies a statement or group of statements in the procedure to be run. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. The Else (ELSE) command can be used with the IF command to specify a statement or group of statements to be run if the condition expressed by the IF command is false. The command includes an expression, which is tested (true or false), and a THEN parameter that specifies the action to be taken if the expression is true. The IF command is formatted as follows:
IF COND(logical-expression) THEN(CL-command)

The logical expression on the COND parameter can be a single logical variable or constant, or it must describe a relationship between two or more operands; the expression is then evaluated as true or false. If the condition described by the logical expression is evaluated as true, the procedure processes the CL command on the THEN parameter. This may be a single command, or a group of commands. If the condition is not true, the procedure runs the next sequential command. Both COND and THEN are keywords on the command, and they can be omitted for positional entry. The following are syntactically correct uses of this command:
IF COND(&RESP=1) THEN(CALL CUS210) IF (&A *EQ &B) THEN(GOTO LABEL) IF (&A=&B) GOTO LABEL

Blanks are required between the command name (IF) and the keyword (COND) or value (&A). No blanks are permitted between the keyword, if specified, and the left parenthesis enclosing the value. The following example is about conditional processing with an IF command. Processing branches in different ways depending on the evaluation of the logical expression in the IF commands. Assume, for instance, that at the start of the following code, the value of &A is 2 and the value of &C is 4.
IF (&A=2) THEN(GOTO FINAL) IF (&A=3) THEN(CHGVAR &C 5) . . . FINAL: IF (&C=5) CALL PROGA ENDPGM

In this case, the procedure processes the first IF command before branching to FINAL, skipping the intermediate code. It does not return to the second IF command. At FINAL, because the test for &C=5 fails, PROGA is not called. The procedure then processes the next command, ENDPGM, which signals the end of the procedure, and returns control to the calling procedure. Processing logic would be different if, using the same code, the initial values of the variables were different. For instance, if at the beginning of this code the value of &A is 3 and the value of &C is 4, the first IF statement is evaluated as false. Instead of processing the GOTO FINAL command, the procedure ignores the first IF statement and moves on to the next one. The second IF statement is evaluated as true, and the value of &C is changed to 5. Subsequent statements, not shown here, are also processed consecutively. When processing reaches the last IF statement, the condition &C=5 is evaluated as true, and PROGA is called. A series of consecutive IF statements are run independently. For instance:

Control language

183

PGM /* IFFY */ DCL &A.. DCL &B.. DCL &C.. DCL &D.. DCL &AREA *CHAR LEN(5) VALUE(YESNO) DCL &RESP.. IF (&A=&B) THEN(GOTO END) /* IF #1 */ IF (&C=&D) THEN(CALL PGMA) /* IF #2 */ IF (&RESP=1) THEN(CHGVAR &C 2) /* IF #3 */ IF (%SUBSTRING(&AREA 1 3) *EQ YES) THEN(CALL PGMB) CHGVAR &B &C . . . END: ENDPGM

/*

IF #4

*/

If, in this example, &A is not equal to &B, the next statement is run. If &C is equal to &D, PGMA is called. When PGMA returns, the third IF statement is considered, and so on. An embedded command is a command that is completely enclosed in the parameter of another command. In the following examples, the Change Variable (CHGVAR) command and the DO command are embedded:
IF (&A *EQ &B) THEN(CHGVAR &A (&A+1)) IF (&B *EQ &C) THEN(DO) . . . ENDDO

Related reference *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. DO command and DO groups in a CL program or procedure on page 188 The Do (DO) command allows you to process a group of commands together. ELSE command in a CL program or procedure The Else (ELSE) command is a way of specifying alternative processing if the condition on the associated If (IF) command is false. Embedded IF commands in a CL program or procedure on page 187 An If (IF) command can be embedded in another IF command. Related information CL command finder If (IF) command

ELSE command in a CL program or procedure

The Else (ELSE) command is a way of specifying alternative processing if the condition on the associated If (IF) command is false. The IF command can be used without the ELSE command:
IF (&A=&B) THEN(CALLPRC PROCA) CALLPRC PROCB

In this case, PROCA is called only if &A=&B, but PROCB is always called.

184

System i: Programming Control language

If you use an ELSE command in this procedure, however, the processing logic changes. In the following example, if &A=&B, PROCA is called, and PROCB is not called. If the expression &A=&B is not true, PROCB is called.
IF (&A=&B) THEN(CALLPRC PROCA) ELSE CMD(CALLPRC PROCB) CHGVAR &C 8

The ELSE command must be used when a false evaluation of an IF expression leads to a distinct branch (that is, an exclusive either/or branch). The real usefulness of the ELSE command is best demonstrated when combined with Do groups. In the following example, the Do group might not be run, depending on the evaluation of the IF expression, but the remaining commands are always processed.

With the ELSE command you can specify that a command or set of commands be processed only if the expression is not true, thus completing the logical alternatives.

Control language

185

Each ELSE command must have an associated IF command preceding it. If nested levels of IF commands are present, each ELSE command is matched with the innermost IF command that has not already been matched with another ELSE command.
IF ... THEN ... IF ...THEN(DO) IF ...THEN(DO) . . . ENDDO ELSE DO IF ...THEN(DO) . . . ENDDO ELSE DO . . . ENDDO ENDDO ELSE IF ... THEN ... IF ... THEN ... IF ... THEN ...

In reviewing your procedure for matched ELSE commands, always start with the innermost set. The ELSE command can be used to test a series of mutually exclusive options. In the following example, after the first successful IF test, the embedded command is processed and the procedure processes the Reclaim Resources (RCLRSC) command.

186

System i: Programming Control language

IF COND(&OPTION=1) THEN(CALLPRC PRC(ADDREC)) ELSE CMD(IF COND(&OPTION=2) THEN(CALLPRC PRC(DSPFILE))) ELSE CMD(IF COND(&OPTION=3) THEN(CALLPRC PRC(PRINTFILE))) ELSE CMD(IF COND(&OPTION=4) THEN(CALLPRC PRC(DUMP))) RCLRSC RETURN

Related reference IF command in a CL program or procedure on page 183 The If (IF) command is used to state a condition that, if true, specifies a statement or group of statements in the procedure to be run. *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Related information CL command finder Else (ELSE) command

Embedded IF commands in a CL program or procedure

An If (IF) command can be embedded in another IF command. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. Embedding an IF command can occur when the command to be processed under a true evaluation (the CL command placed on the THEN parameter) is itself another IF command:
IF (&A=&B) THEN(IF (&C=&D) THEN(GOTO END)) GOTO START

This can be useful when several conditions must be satisfied before a certain command or group of commands is run. In the preceding example, if the first expression is true, the system then reads the first THEN parameter; within that, if the &C=&D expression is evaluated as true, the system processes the command in the second THEN parameter, GOTO END. Both expressions must be true to process the GOTO END command. If one or the other is false, the GOTO START command is run. Note the use of parentheses to organize expressions and commands. Up to 25 levels of such embedding are permitted in CL programming. As the levels of embedding increase and logic grows more complex, you might want to enter the code in free-form design to clarify relationships:
PGM DCL &A *DEC 1 DCL &B *CHAR 2 DCL &RESP *DEC 1 IF (&RESP=1) + IF (&A=5) + IF (&B=NO) THEN(DO) . . . ENDDO CHGVAR &A VALUE(8) CALL PGM(DAILY) ENDPGM

The preceding IF series is handled as one embedded command. Whenever any one of the IF conditions fails, processing branches to the remainder of the code (Change Variable (CHGVAR) and subsequent

Control language

187

commands). If the purpose of this code is to accumulate a series of conditions, all of which must be true for the Do group to process, it could be more easily coded using *AND with several expressions in one command. In some cases, however, the branch must be different depending on which condition fails. You can accomplish this by adding an ELSE command for each embedded IF command:
PGM DCL &A ... DCL &B ... DCL &RESP ... IF (&RESP=1) + IF (&A=5) + IF (&B=NO) THEN(DO) . . . SNDPGMMSG ... . . . ENDDO ELSE CALLPRC PROCA ELSE CALLPRC PROCB CHGVAR &A 8 CALLPRC PROC(DAILY) ENDPGM

Here, if all conditions are true, the Send Program Message (SNDPGMMSG) command is processed, followed by the Change Variable (CHGVAR) command. If the first and second conditions (&RESP=1 and &A=5) are true, but the third (&B=NO) is false, PROCA is called; when PROCA returns, the CHGVAR command is processed. If the second conditions fails, PROCB is called (&B=NO is not tested), followed by the CHGVAR command. Finally, if &RESP does not equal 1, the CHGVAR command is immediately processed. The ELSE command has been used to provide a different branch for each test. Note: The following three examples are correct syntactical equivalents to the embedded IF command in the preceding example:
IF (&RESP=1) THEN(IF (&A=5) THEN(IF (&B=NO) THEN(DO))) IF (&RESP=1) THEN + (IF (&A=5) THEN + (IF (&B=NO) THEN(DO))) IF (&RESP=1) + (IF (&A=5) + (IF (&B=NO) THEN(DO)))

Related reference IF command in a CL program or procedure on page 183 The If (IF) command is used to state a condition that, if true, specifies a statement or group of statements in the procedure to be run. *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Related information CL command finder If (IF) command

DO command and DO groups in a CL program or procedure

The Do (DO) command allows you to process a group of commands together.

188

System i: Programming Control language

The group is defined as all those commands between the DO command and the corresponding End Do Group (ENDDO) command. Processing of the group is typically conditioned on the evaluation of an associated command. Do groups are most frequently associated with the IF, ELSE, or MONMSG commands. Here is an example of a Do group.

If the logical expression (&A=&B) is true, then the Do group is processed. If the expression is not true, then processing starts after the ENDDO command; the Do group is skipped. In the following procedure, if &A is not equal to &B, the system calls PROCB. PROCA is not called, nor are any other commands in the Do group processed.

Do groups can be nested within other Do groups, up to a maximum of 25 levels of nesting. There are three levels of nesting in the following example. Note how each Do group is completed by an ENDDO command.

Control language

189

In this example, if &A in the first nest does not equal 5, PGMC is called. If &A equals 5, the statements in the second Do group are processed. If &AREA in the second Do group does not equal YES, procedure ACCTSPAY is called, because processing moves to the next command after the Do group. The CL compiler does not indicate the beginning or ending of Do groups. If the CL compiler notes any unbalanced conditions, it is not easy to detect the actual errors. Related reference IF command in a CL program or procedure on page 183 The If (IF) command is used to state a condition that, if true, specifies a statement or group of statements in the procedure to be run. Related information CL command finder Do Group (DO) command

DOUNTIL command in a CL program or procedure

The Do Until (DOUNTIL) command processes a group of CL commands one or more times. The group of commands is defined as those commands between the DOUNTIL and the matching End Do (ENDDO) command. After the group of commands is processed, the stated condition is evaluated. If the condition is true, the DOUNTIL group will be exited and processing will resume with the next command following the associated ENDDO. If the condition is false, the group will continue processing with the first command in the group. The logical expression on the COND parameter can be a single logical variable or constant, or it must describe a relationship between two or more operands; the expression is then evaluated as true or false.

190

System i: Programming Control language

The following example is about conditional processing with a DOUNTIL command.

DOUNTIL (&LGL) . . . CHGVAR &INT (&INT + 1) IF (&INT *GT 5) (CHGVAR &LGL 1) ENDDO

The body of the DOUNTIL group will be run at least one time. If the initial value of the &INT variable is 5 or more, &LGL will be set to true on the first time and processing will continue following the ENDDO when the expression is evaluated at the end of the group. If the initial value is less than 5, the body of the group will continue to be repeated until the value of &INT is greater than 5 and the value of &LGL is changed to true. The Leave (LEAVE) command can be used to exit the DOUNTIL group and resume processing following the ENDDO. The ITERATE command can be used to skip the remaining commands in the group and evaluate the stated condition immediately. Related reference *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Related information CL command finder Do Until (DOUNTIL) command

DOWHILE command in a CL program or procedure

The Do While (DOWHILE) command lets you process a group of commands zero or more times while the value of a logical expression is true. The DOWHILE command is used to state a condition that, if true, specifies a command or group of commands in the procedure to run. The group of commands is defined as those commands between the DOWHILE and the matching End Do (ENDDO) command. After the group of commands is processed, the stated condition is evaluated. If the condition is false, the DOWHILE group will be exited and processing will resume with the next command following the associated ENDDO. If the condition is true, the group will continue processing with the first command in the group. When the ENDDO command is reached, control returns to the DOWHILE command to again evaluate the condition. The logical expression on the COND parameter can be a single logical variable or constant, or it must describe a relationship between two or more operands; the expression is then evaluated as true or false. The following example is about conditional processing with a DOWHILE command.
DOWHILE (&LGL) . . . IF (&INT *EQ 2) (CHGVAR &LGL 0) ENDDO

When the DOWHILE group is processed, the stated condition will be evaluated. If the condition is true, the group of commands in the DOWHILE group is processed. If the condition is false, processing continues with the command following the associated ENDDO command.

Control language

191

If the value of &LGL is true, the commands in the DOWHILE group will be run until &INT is equal to 2 causing the &LGL variable value to be set to false. The Leave (LEAVE) command can be used to exit the DOWHILE group and resume processing following the ENDDO. The ITERATE command can be used to skip the remaining commands in the group and evaluate the stated condition immediately. Related reference *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Related information CL command finder Do While (DOWHILE) command

DOFOR command in a CL program or procedure

The Do For (DOFOR) command lets you process a group of commands a specified number of times. The DOFOR command specifies a variable, its initial value, an increment or decrement amount, and a terminal value condition. The format of the DOFOR command is:
DOFOR VAR(integer-variable) FROM(initial-value) TO(end-value) BY(integer-constant)

When processing of a DOFOR group is begun, the integer-variable specified on the VAR parameter is initialized to the initial-value specified on the FROM parameter. The value of the integer-variable is compared to the end-value as specified on the TO parameter. When the integer-constant on the BY parameter is positive, the comparison checks for integer-variable greater than the end-value. If the integer-constant on the BY parameter is negative, the comparison checks for integer-variable less than the end-value. If the condition is not true, the body of the DOFOR group is processed. When the ENDDO is reached, the integer-constant from the BY parameter is added to the integer-value and the condition is evaluated again. The following example is about conditional processing with a DOFOR command.
CHGVAR &INT2 0 DOFOR VAR(&INT) FROM(2) TO(4) BY(1) . . . CHGVAR &INT2 (&INT2 + &INT) ENDDO /* &INT2 = 9 after running the DOFOR group 3 times */

When the DOFOR group is processed, &INT is initialized to 2 and the value of &INT is checked to see if it is greater than 4. It is not, so the body of the group is processed. On the second iteration of the group, one is added to &INT and the check is repeated. It is less than 4, so the DOFOR group is processed again. On reaching the ENDDO the second time, the value of &INT is again incremented by 1. &INT now has a value of 4. Because &INT is still less than or equal to 4, the DOFOR group is processed again. On reaching the ENDDO the third time, the value of &INT is again incremented by 1. This time, the value is 5, and processing continues with the command following the ENDDO. The LEAVE command can be used to exit the DOFOR group and resume processing following the ENDDO. The ITERATE command can be used to skip the remaining commands in the group, increment the controlling variable, and evaluate the end-value condition immediately. Related information CL command finder

192

System i: Programming Control language

Do For (DOFOR) command

ITERATE command in a CL program or procedure

The Iterate (ITERATE) command can be used to skip the remaining commands in an active DOWHILE, DOUNTIL, or DOFOR group. ITERATE is not valid with simple DO command groups. An ITERATE command without a label will skip to the ENDDO of the innermost active DO group. Specifying a label skips to the ENDDO of the DO associated with the label. The following example illustrates use of the ITERATE command:
DO_1: DO_2:DOWHILE &LGL DO_3: DOFOR &INT FROM(0) TO(99) . . . IF (&A *EQ 12) THEN (ITERATE DO_1) . . /* Not processed if &A equals 12 */ . IF (&A *GT 12) ITERATE . . /* Not processed if &A greater than 12 */ . ENDDO . . . IF (&A *LT 0) (ITERATE DO_1) . . /* Not processed if &A less than zero */ . ENDDO

In this example, the labels DO_1 and DO_2 are associated with the DOWHILE group. They can be specified on an ITERATE command appearing in either the DOWHILE or DOFOR group. When &A is equal to 12, the ITERATE DO_1 command is run. Processing continues at the ENDDO associated with the DOWHILE command. The value of &LGL is evaluated and, if true, continues with the DOFOR following the DOWHILE. If &LGL is false, processing continues with the CL command following the second ENDDO. If &A is not equal to 12 but is greater than 12, processing continues with the ENDDO of the DOFOR group. The value of &INT is incremented and compared to the ending value of 99. If &INT is less than or equal to 99, processing continues with the first command following the Do For (DOFOR) command. If &INT is greater than 99, processing continues with the next command following the first ENDDO. When the third IF command is processed and &A is less than zero, processing continues with the second ENDDO. The value of &LGL is evaluated and, if false, control passes to the command following the ENDDO. If true, processing resumes with the Do For (DOFOR) command following the DOWHILE. Related information CL command finder Iterate (ITERATE) command

LEAVE command in a CL program or procedure

The Leave (LEAVE) command can be used to exit an active DOWHILE, DOUNTIL, or DOFOR group.

Control language

193

It provides a structured manner to leave an active group without resorting to the use of the Goto (GOTO) command. LEAVE is not valid with simple Do (DO) command groups. A LEAVE command without a label will leave the innermost active DO group. Specifying a label allows the processing to break out of one or more enclosing groups. The following illustrates use of the LEAVE command:
DO_1: DO_2:DOWHILE &LGL DO_3: DOFOR &INT FROM(0) TO(99) . . . IF (&A *EQ 12) THEN(LEAVE DO_1) . . /* Not processed if &A equals 12 */ . IF (&A *GT 12) LEAVE . . /* Not processed if &A greater than 12 */ . ENDDO . . . IF (&A *LT 0) (LEAVE DO_1) . . /* Not processed if &A less than zero */ . ENDDO

In this example, the labels DO_1 and DO_2 are associated with the DOWHILE group. They can be specified on a LEAVE command appearing in either the DOWHILE or DOFOR group. When &A is equal to 12, the LEAVE DO_1 command is run and processing continues with the CL command following the second ENDDO. If &A is not equal to 12 but is greater than 12, the DOFOR group is exited and processing continues with next command following the first ENDDO. When the third If (IF) command is processed and &A is less than zero, processing continues with the next command following the first ENDDO. Related information CL command finder Leave (LEAVE) command | CALLSUBR command in a CL program or procedure | The Call Subroutine (CALLSUBR) command is used in a CL procedure for passing control to a subroutine | defined within the same procedure. | | | | | | | | | The CALLSUBR command has two parameters: Subroutine (SUBR), which contains the name of the subroutine to which control is to be transferred to, and Return value (RTNVAL), which specifies the variable that will contain the return value from the called subroutine. See the following example:
CALLSUBR SUBR(mysubr) RTNVAL(&myrtnvar)

The subroutine mysubr must be defined in the procedure by the Subroutine (SUBR) parameter of a SUBR command. The variable &myrtnvar must be defined as TYPE(*INT) LEN(4), and will contain the value from the Return value (RTNVAL) parameter of either a Return from Subroutine (RTNSUBR) or the End Subroutine (ENDSUBR) command found in subroutine mysubr. If no RTNVAL parameter is defined, the return value from the subroutine is ignored.

194

System i: Programming Control language

| | | | | |

The CALLSUBR command can be placed anywhere within the procedure, including other subroutines, with the exception of a program-level Monitor Message (MONMSG) command. Each CALLSUBR command, when run, places a return address onto the subroutine stack, and the size of the stack can be changed with the use of the Subroutine Stack (SUBRSTACK) parameter of the Declare Process Options (DCLPRCOPT) command. If a globally monitored message causes a GOTO command to be run, the subroutine stack will be reset by the next CALLSUBR command that is run. See the following example.

| Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569. | PGM | DCL VAR(&myrtnvar) TYPE(*INT) LEN(4) | MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(DUMP)) | : | CALLSUBR SUBR(SUBR1) RTNVAL(&myrtnvar) | : | DMPCLPGM | DUMP: CALLSUBR SUBR(SUBR2) | : | SUBR SUBR(SUBR1) | : | ENDSUBR RTNVAL(12) | : | SUBR SUBR(SUBR2) | : | ENDSUBR | ENDPGM | In this example, the first CALLSUBR command will pass control to the subroutine SUBR1, and the return value of 12 will be placed into the variable &myrtnvar when control returns. If a message is monitored by the MONMSG command, the Goto (GOTO) command will be run and control will branch to label DUMP, the CL procedure will be dumped by DMPCLPGM, and the next CALLSUBR to subroutine SUBR2 will reset the subroutine stack. Related reference SUBR command and subroutines in a CL program or procedure on page 196 The Subroutine (SUBR) command is used in a CL procedure, along with the End Subroutine (ENDSUBR) command, to delimit the group of commands that define a subroutine. Related information Declare Processing Options (DCLPRCOPT) command | CL command finder | Call Subroutine (CALLSUBR) command | | | | | | | | | | |

SELECT command and SELECT groups in a CL program or procedure

The Select (SELECT) command is used to identify one or more conditions and an associated group of commands to process when that condition is true. A special group of commands can also be specified to be processed when none of the stated conditions are true. Only one of the groups of commands identified by When (WHEN) or Otherwise (OTHERWISE) commands will be processed within the group. The general structure of the SELECT command is as follows:
SELECT WHEN (condition-1) THEN(command-1) . . . WHEN (condition-n) THEN(command-n) OTHERWISE command-x ENDSELECT
Control language

195

A SELECT group must specify at least one WHEN command. The WHEN command includes an expression, which is tested (true or false), and an optional THEN parameter that specifies the action to take if the condition is true. The logical expression on the COND parameter can be a single logical variable or constant, or it must describe a relationship between two or more operands; the expression is then evaluate as true or false. If the condition described by the logical expression is evaluated as true, the procedure processes the CL command on the THEN parameter. This can be a single command or a group of commands specified by the DO, DOWHILE, DOUNTIL, or DOFOR commands. If the condition is not true, the condition specified on the next WHEN command in the SELECT group is evaluated. If there is no WHEN command following this one, the command identified by the OTHERWISE command, if any, is processed. If there is no next WHEN and no OTHERWISE command, processing continues with the next command following the associated ENDSELECT command.
SELECT WHEN (&LGL) WHEN (&INT *LT 0) THEN(CHGVAR &INT 0) WHEN (&INT *GT 0) (DOUNTIL (&INT *EQ 0)) CHGVAR &INT (&INT - 1) ENDDO OTHERWISE (CHGVAR &LGL 1) ENDSELECT

If the initial value of &LGL is true (1), processing continues with the command following the ENDSELECT, because there is no THEN parameter. If the initial value of &LGL is false (0), the COND of the second WHEN is evaluated. If &INT is less than zero, the CHGVAR is processed, setting the value of &INT to zero. Processing then continues with the command following the ENDSELECT. If the first two conditions are not met, the value of &INT is checked to determine if it is greater than zero. If the value is greater than zero, the DOUNTIL group is entered and the value of &INT decremented until it reaches zero. When &INT reaches zero, the DOUNTIL group is exited and processing continues with the next command following the ENDSELECT. If none of the conditions on any of the WHEN commands is evaluated as true, the CHGVAR specified on the CMD parameter of the OTHERWISE command is processed. The value of &INT remains unchanged while &LGL is set to true. Processing then continues with the next command following the ENDSELECT. Related reference *AND, *OR, and *NOT operators on page 197 The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Related information CL command finder Select (SELECT) command | SUBR command and subroutines in a CL program or procedure | The Subroutine (SUBR) command is used in a CL procedure, along with the End Subroutine (ENDSUBR) | command, to delimit the group of commands that define a subroutine. | The name of the subroutine, as used by the CALLSUBR command, is defined by the SUBR parameter on | the SUBR command. | The first SUBR command that is encountered in a procedure also marks the end of the mainline of that | procedure. All commands from this point forward, with the exception of the ENDPGM command, must | be contained within a subroutine, in other words, between SUBR and ENDSUBR commands. The SUBR

196

System i: Programming Control language

| and ENDSUBR commands must be matched pairs, and subroutines cannot be nested; in other words, no | SUBR SUBR - ENDSUBR ENDSUBR nesting of subroutines is allowed. | | | | | Both the ENDSUBR and RTNSUBR commands can be used to exit a subroutine, and when processed, control is returned to the command immediately following the Call Subroutine (CALLSUBR) command that called the subroutine. Both commands have an optional RTNVAL parameter, which can be anything that can be stored in a CL variable of TYPE(*INT) and LEN(4). If no RTNVAL parameter is defined on the Return Subroutine (RTNSUBR) or ENDSUBR command, a value of zero is returned.

| The following example is about the general structure of a CL procedure that contains a subroutine. | Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569. | PGM | DCLPRCOPT SUBRSTACK(25) | DCL VAR(&RTNVAR) TYPE(*INT) LEN(4) | : | CALLSUBR SUBR(SUBR1) RTNVAL(&RTNVAR) | : | SUBR SUBR(SUBR1) | : | RTNSUBR RTNVAL(-1) | : | ENDSUBR | ENDPGM | | | | | | | | | | | | | | | In this example, the Declare Processing Options (DCLPRCOPT) command was used to specify the size of the subroutine stack to be 25. The variable &RTNVAR is used to contain the return value from the subroutine. The CALLSUBR command will transfer control to the subroutine SUBR1, as defined by the SUBR command. If the RTNSUBR command is run, the value of &RTNVAR will be -1, if the ENDSUBR command is run, &RTNVAR will equal 0. If no RTNVAL parameter was defined on the CALLSUBR command, the return value from the subroutine would be ignored. Related reference CALLSUBR command in a CL program or procedure on page 194 The Call Subroutine (CALLSUBR) command is used in a CL procedure for passing control to a subroutine defined within the same procedure. Related information CL command finder Subroutine (SUBR) command End Subroutine (ENDSUBR) command

*AND, *OR, and *NOT operators

The logical operators *AND and *OR specify the relationship between operands in a logical expression. The logical operator *NOT is used to negate logical variables or constants. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. *AND and *OR are the reserved values used to specify the relationship between operands in a logical expression. The ampersand symbol (&) can replace the reserved value *AND, and the vertical bar (|) can replace *OR. The reserved values must be preceded and followed by blanks. The operands in a logical expression consist of relational expressions or logical variables or constants separated by logical operators. The *AND operator indicates that both operands (on either side of the operator) have to be true to produce a true result. The *OR operator indicates that one or the other of its operands must be true to produce a true result.

Control language

197

Note: Using the ampersand symbol or the vertical bar can cause problems because the symbols are not at the same code point for all code pages. To avoid this, use *AND and *OR instead of the symbols. Use operators other than logical operators in expressions to indicate the actions to perform on the operands in the expression or the relationship between the operands. There are three kinds of operators other than logical operators: v Arithmetic (+, -, *, /) v Character (*CAT, ||, *BCAT, |>, *TCAT, |<) v Relational (*EQ, =, *GT, >, *LT, <, *GE, >=, *LE, <=, *NE, =, *NG, >, *NL, <) The following examples are about logical expressions:
((&C *LT 1) *AND (&TIME *GT 1430)) (&C *LT 1 *AND &TIME *GT 1430) ((&C < 1) & (&TIME>1430)) ((&C< 1) & (&TIME>1430))

In each of these cases, the logical expression consists of three parts: two operands and one operator (*AND or *OR, or their symbols). It is the type of operator (*AND or *OR) that characterizes the expression as logical, not the type of operand. Operands in logical expressions can be logical variables or other expressions, such as relational expressions. (Relational expressions are characterized by &gt, &lt, or = symbols or corresponding reserved values.) For instance, in following example the entire logical expression is enclosed in parentheses, and both operands are relational expressions, also enclosed separately in parentheses:
((&C *LT 1) *AND (&TIME *GT 1430))

As you can see from the second example of logical expressions, the operands need not be enclosed in separate parentheses, but it is recommended for clarity. Parentheses are not needed because *AND and *OR have different priorities. *AND is always considered before *OR. For operators of the same priority, parentheses can be used to control the order in which operations are performed. A simple relational expression can be written as the condition in a command:
IF (&A=&B) THEN(DO) . . . ENDDO

The operands in this relational expression could also be constants. If you want to specify more than one condition, you can use a logical expression with relational expressions as operands:
IF ((&A=&B) *AND (&C=&D)) THEN(DO) . . . ENDDO

The series of dependent IF commands cited as an example in Embedded IF commands in a CL program or procedure on page 187 could be coded:
PGM DCL &RESP *DEC 1 DCL &A *DEC 1 DCL &B *CHAR 2 IF ((&RESP=1) *AND (&A=5) *AND (&B=NO)) THEN(DO) . . .

198

System i: Programming Control language

ENDDO CHGVAR &A VALUE(8) CALLPRC PROC(DAILY) ENDPGM

Here the logical operators are again used between relational expressions. Because a logical expression can also have other logical expressions as operands, quite complex logic is possible:
IF (((&A=&B) *OR (&A=&C)) *AND ((&C=1) *OR (&D=0))) THEN(DO)

In this case, &D is defined as a logical variable. The result of the evaluation of any relational or logical expression is a 1 or 0 (true or false). The dependent command is processed only if the complete expression is evaluated as true (1). The following command is interpreted in these terms:
IF ((&A = &B) *AND (&C = &D)) THEN(DO) ((true1) *AND (not true0)) (not true 0)

The expression is finally evaluated as not true (0), and, therefore, the DO is not processed. For an explanation of how this evaluation was reached, see the matrices later in this section. This same process is used to evaluate a logical expression using logical variables, as in this example:
PGM DCL &A *LGL DCL &B *LGL IF (&A *OR &B) THEN(CALL PGM(PGMA)) . . . ENDPGM

Here the conditional expression is evaluated to see if the value of &A or of &B is equal to 1 (true). If either is true, the whole expression is true, and PGMA is called. The final evaluation arrived at for all these examples of logical expressions is based on standard matrices comparing two values (referred to here as &A and &B) under an *OR or *AND operator. Use the following matrix when using *OR with logical variables or constants: If &A is: 0 0 1 1 and &B is: 0 1 0 1 the OR expression is: 0 1 1 1 In short, for multiple OR operators with logical variables or constants, the expression is false (0) if all values are false. The expression is true (1) if any values are true.
PGM DCL &A DCL &B DCL &C IF (&A *LGL VALUE(0) *LGL VALUE(1) *LGL VALUE(1) *OR &B *OR &C) THEN(CALL PGMA)

Control language

199

. . . ENDPGM

Here the values are not all false; therefore, the expression is true, and PGMA is called. Use the following matrix when evaluating a logical expression with *AND with logical variables or constants: If &A is: 0 0 1 1 and &B is: 0 1 0 1 the ANDed expression is: 0 0 0 1 For multiple AND operators with logical variables or constants, the expression is false (0) when any value is false, and true when they are all true.
PGM DCL &A DCL &B DCL &C IF (&A . . . ENDPGM *LGL *LGL *LGL *AND VALUE(0) VALUE(1) VALUE(1) &B *AND &C) THEN(CALL PGMA)

Here the values are not all true; therefore, the expression is false, and PGMA is not called. These logical operators can only be used within an expression when the operands represent a logical value, as in the preceding examples. It is incorrect to attempt to use OR or AND for variables that are not logical. For instance:
PGM DCL &A *CHAR 3 DCL &B *CHAR 3 DCL &C *CHAR 3 Incorrect: IF (&A *OR &B *OR &C = YES) THEN...

The correct coding for this would be:

IF ((&A=YES) *OR (&B=YES) *OR (&C=YES)) THEN...

In this case, the ORing occurs between relational expressions. The logical operator *NOT (or ) is used to negate logical variables or constants. Any *NOT operators must be evaluated before the *AND or *OR operators are evaluated. Any values that follow *NOT operators must be evaluated before the logical relationship between the operands is evaluated.
PGM DCL &A *LGL 1 DCL &B *LGL 0 IF (&A *AND *NOT &B) THEN(CALL PGMA)

In this example, the values are all true; therefore, the expression is true, and PGMA is called.

200

System i: Programming Control language

PGM DCL &A *LGL DCL &B *CHAR 3 VALUE(ABC) DCL &C *CHAR 3 VALUE(XYZ) CHGVAR &A VALUE(&B *EQ &C) IF (&A) THEN(CALLPRC PROCA)

In this example, the value is false, therefore, PROCA is not called. Related reference IF command in a CL program or procedure on page 183 The If (IF) command is used to state a condition that, if true, specifies a statement or group of statements in the procedure to be run. ELSE command in a CL program or procedure on page 184 The Else (ELSE) command is a way of specifying alternative processing if the condition on the associated If (IF) command is false. DOUNTIL command in a CL program or procedure on page 190 The Do Until (DOUNTIL) command processes a group of CL commands one or more times. DOWHILE command in a CL program or procedure on page 191 The Do While (DOWHILE) command lets you process a group of commands zero or more times while the value of a logical expression is true. SELECT command and SELECT groups in a CL program or procedure on page 195 The Select (SELECT) command is used to identify one or more conditions and an associated group of commands to process when that condition is true. | %ADDRESS built-in function in a CL program or procedure | The address built-in function (%ADDRESS or %ADDR) can be used to change or test the memory | address stored in a CL pointer variable and can only be used within a CL procedure. | In a CHGVAR command, you can specify the %ADDRESS function to change the value of a pointer | variable. On the IF command, %ADDRESS function can be specified on the COND parameter to check | the value stored in a pointer variable. | The format of the address built-in function is: | %ADDRESS(variable name) | or | %ADDR(variable name) | | | | | | | | | | | | | | In the following example, pointer variable &P1 is initialized to the address of the first byte of character variable &C1. Later in the procedure, the pointer is checked using the %ADDRESS function to see if it still points to &C1 and, if not, resets &P1 to the first byte of CL variable &C1 using the %ADDRESS function. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL &C1 *CHAR DCL &P1 *PTR : IF COND(&P1 *NE THEN(CHGVAR : ENDPGM 10 ADDRESS(&C1) %ADDRESS(&C1)) + &P1 %ADDRESS(&C1))

| Note: The %ADDRESS function cannot be used to store the address offset stored in a pointer variable. To store the address offset in a pointer variable, you need to use the %OFFSET built-in function. |
Control language

201

| | | | | | |

Related tasks Changing the value of a variable on page 177 You can change the value of a CL variable using the Change Variable (CHGVAR) command. Related reference Built-in functions for CL on page 106 Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions.

%BINARY built-in function

The binary built-in function (%BINARY or %BIN) interprets the contents of a specified CL character variable as a signed binary integer. The starting position begins at the position specified and continues for a length of 2 or 4 characters. The syntax of the binary built-in function is shown in the following example:
%BINARY(character-variable-name starting-position length)

You can also code it like this example:

%BIN(character-variable-name starting-position length)

The starting position and length are optional. However, if the starting position and length are not specified, a starting position of 1 and length of the character variable that is specified are used. In that case, you must declare the length of the character variable as either 2 or 4. If the starting position is specified, you must also specify a constant length of 2 or 4. The starting position must be a positive number equal to or greater than 1. If the sum of the starting position and the length is greater than the length of the character variable, an error occurs. (A CL decimal or integer variable can also be used for the starting position.) You can use the binary built-in function with both the If (IF) and Change Variable (CHGVAR) commands. It can be used by itself or as part of an arithmetic or logical expression. You can also use the binary built-in function on any command parameter that is defined as numeric (TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4) with EXPR(*YES). When the binary built-in function is used with the condition (COND) parameter on the IF command or with the VALUE parameter on the Change Variable (CHGVAR) command, the contents of the character variable is interpreted as a binary-to-decimal conversion. When the binary built-in function is used with the VAR parameter on the Change Variable (CHGVAR) command, the decimal value in the VALUE parameter is converted to a 2-byte or 4-byte signed binary integer and the result stored in the character variable at the starting position specified. Decimal fractions are truncated. The system uses the binary built-in function on the RTNVAL parameter of the Call Bound Procedure (CALLPRC) command to indicate that the calling procedure expects the called procedure to return a signed binary integer. A 2-byte character variable can hold signed binary integer values from -32 768 through 32 767. A 4-byte character variable can hold signed binary integer values from -2 147 483 648 through 2 147 483 647. The following examples are about the binary built-in function: v
DCL VAR(&B2) TYPE(*CHAR) DCL VAR(&N) TYPE(*DEC) CHGVAR &N %BINARY(&B2) LEN(2) LEN(3 0) VALUE(X001C)

202

System i: Programming Control language

The contents of variable &B2 is treated as a 2-byte signed binary integer and converted to its decimal equivalent of 28. It is then assigned to the decimal variable &N. v
DCL VAR(&N) TYPE(*DEC) DCL VAR(&B4) TYPE(*CHAR) CHGVAR %BIN(&B4) &N LEN(5 0) LEN(4) VALUE(107)

The value of the decimal variable &N is converted to a 4-byte signed binary number and is placed in character variable &B4. Variable &B4 will have the value of X0000006B. v
DCL VAR(&P) TYPE(*CHAR) LEN(100) DCL VAR(&L) TYPE(*DEC) LEN(5 0) CHGVAR &L VALUE(%BIN(&P 1 2) * 5)

The first two characters of variable &P is treated as a signed binary integer, converted to its decimal equivalent, and multiplied by 5. The product is assigned to the decimal variable &L. v
DCL VAR(&X) TYPE(*CHAR) LEN(50) CHGVAR %BINARY(&X 15 2) VALUE(122.56)

The number 122.56 is truncated to the whole number 122 and is then converted to a 2-byte signed binary integer and is placed at positions 15 and 16 of the character variable &X. Positions 15 and 16 of variable &X will contain the hexadecimal equivalent of X007A. v
DCL VAR(&B4) TYPE(*CHAR) LEN(4) CHGVAR %BIN(&B4) VALUE(-57)

The value -57 is converted to a 4-byte signed binary integer and assigned to the character variable &B4. The variable &B4 will then contain the value XFFFFFFC7. v
DCL VAR(&B2) TYPE(*CHAR) DCL VAR(&C5) TYPE(*CHAR) CHGVAR &C5 %BINARY(&B2) LEN(2) LEN(5) VALUE(XFF1B)

The contents of variable &B2 is treated as a 2-byte signed binary integer and converted to its decimal equivalent of -229. The number is converted to character form and stored in the variable character &C5. The character variable &C5 will then contain the value -0229. v
DCL VAR(&C5) TYPE(*CHAR) LEN(5) DCL VAR(&B2) TYPE(*CHAR) LEN(2) CHGVAR %BINARY(&B2) VALUE(&C5) VALUE( 1253)

The character number 1253 in character variable &C5 is converted to a decimal number. The decimal number 1253 is then converted to a 2-byte signed binary integer and stored in the variable &B2. The variable &B2 will then have the value X04E5. v
DCL IF VAR(&S) TYPE(*CHAR) LEN(100) (%BIN(&S 1 2) *GT 10) THEN( SNDPGMMSG MSG(Too many in list.) )

The first 2 bytes of the character variable &S are treated as a signed binary integer when compared to the number 10. If the binary number has a value larger than 10, then the Send Program Message (SNDPGMMSG) command is run. v
DCL VAR(&RTNV) TYPE(*CHAR) LEN(4) CALLPRC PRC(PROCA) RTNVAL(%BIN(&RTNV 1 4))

Procedure PROCA returns a 4-byte integer which is stored in variable &RTNV. Related tasks

Control language

203

Changing the value of a variable on page 177 You can change the value of a CL variable using the Change Variable (CHGVAR) command. Related reference Built-in functions for CL on page 106 Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions. Related information CL command finder If (IF) command Change Variable (CHGVAR) command Call Bound Procedure (CALLPRC) command Send Program Message (SNDPGMMSG) command | %OFFSET built-in function | The offset built-in function (%OFFSET or %OFS) can be used to store or change the offset portion of a CL | pointer variable and can only be used within a CL procedure. | In a CHGVAR command, the %OFFSET function can be used two different ways: | v You can specify the %OFFSET function for the variable (VAR parameter) to set the offset portion of a pointer variable. | | v You can specify the %OFFSET function for the value (VALUE parameter) to which the variable is to be changed. | | In an IF command, the %OFFSET function can be specified in the expression (COND parameter) and is | treated like a four-byte unsigned integer value. | The format of the offset built-in function is: | %OFFSET(variable name) | or | %OFS(variable name) | | | | | | | | | | | | | | | | | | | | | In the following example, pointer variable &P1 has no initial value specified and therefore is initialized to null. The first CHGVAR command stores the offset from the null pointer value in integer variable &OFF1; the command runs without an error, and the value of &OFF1 is probably zero, though the offset for a null pointer is not defined. The second CHGVAR command sets &P1 to the address of local character variable &C1; pointer &P1 now points to byte 1 of variable &C1. The third CHGVAR command stores the offset portion of &P1 into the integer variable &OFF2. Note that the offset is from the start of the storage for all automatic variables for the current thread and not from the start of automatic storage for the current program or from the start of variable &C1. The fourth CHGVAR command takes the integer value stored in &OFF2, adds one hundred, and stores the resulting number into the integer variable &OFF3. The fifth CHGVAR command changes the offset portion of pointer &P1 using integer variable &OFF3; pointer &P1 now points to byte 101 of variable &C1. The sixth CHGVAR command calculates the integer expression for the VALUE parameter by storing the offset portion of pointer &P1 into a temporary integer variable and subtracting 20, and then uses this calculated value to reset the offset portion of pointer &P1; pointer &P1 now points to byte 81 of variable &C1. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL DCL DCL DCL &C1 *CHAR 30000 &P1 *PTR &P2 *PTR &OFF1 *UINT 4
System i: Programming Control language

204

| | | | | | | | |

DCL &OFF2 *UINT 4 DCL &OFF3 *UINT 4 CHGVAR &OFF1 %OFFSET(&P1) CHGVAR &P1 %ADDRESS(&C1) CHGVAR &OFF2 %OFFSET(&P1) CHGVAR &OFF3 (&OFF2+100) CHGVAR %OFFSET(&P1) &OFF3 CHGVAR %OFFSET(&P1) (%OFFSET(&P1)-20) ENDPGM

/* /* /* /* /* /*

1 2 3 4 5 6

*/ */ */ */ */ */

| The %OFFSET built-in function cannot be used with a pointer variable that addresses teraspace storage. Related tasks | Changing the value of a variable on page 177 | You can change the value of a CL variable using the Change Variable (CHGVAR) command. | Related reference | Built-in functions for CL on page 106 | Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, | relational, or logical expressions. | Related information | CL command finder | Change Variable (CHGVAR) command |

%SUBSTRING built-in function

The substring built-in function (%SUBSTRING or%SST) produces a character string that is a subset of an existing character string and can only be used within a CL procedure. In a Change Variable (CHGVAR) command, the %SST function can be specified in place of the variable (VAR parameter) to be changed or the value (VALUE parameter) to which the variable is to be changed. In an If (IF) command, the %SST function can be specified in the expression. The format of the substring built-in function is shown in this example:
%SUBSTRING(character-variable-name starting-position length)

It can also be formatted as shown in this example:

%SST(character-variable-name starting-position length)

You can code *LDA in place of the character variable name to indicate that the substring function is performed on the contents of the local data area. The substring function produces a substring from the contents of the specified CL character variable or the local data area. The substring begins at the specified starting position (which can be a variable name) and continues for the length specified (which can also be a variable name). Neither the starting position nor the length can be 0 or negative. If the sum of the starting position and the length of the substring are greater than the length of the entire variable or the local data area, an error occurs. The length of the local data area is 1024. The following examples are about the substring built-in function: v If the first two positions in the character variable &NAME are IN, the program INV210 is called. The entire value of &NAME is passed to INV210 and the value of &ERRCODE is unchanged. Otherwise, the value of &ERRCODE is set to 99.
DCL &NAME *CHAR VALUE(INVOICE) DCL &ERRCODE *DEC (2 0) IF (%SST(&NAME 1 2) *EQ IN) + THEN(CALL INV210 &NAME) ELSE CHGVAR &ERRCODE 99

Control language

205

v If the first two positions of &A match the first two positions of &B, the program CUS210 is called.
DCL &A *CHAR VALUE(ABC) DCL &B *CHAR VALUE(DEF) IF (%SST(&A 1 2) *EQ %SUBSTRING(&B 1 2)) + CALL CUS210

v Position and length can also be variables. This example changes the value of &X beginning at position &Y for the length &Z to 123.
CHGVAR %SST(&X &Y &Z) 123

v If &A is ABCDEFG before this CHGVAR command is run, &A is

CHGVAR %SST(&A 2 3) 123

A123EFG after the command runs. v In this example, the length of the substring, 5, exceeds the length of the operand YES to which it is compared. The operand is padded with blanks so that the comparison is between YESNO and YESbb (where b is a blank). The condition is false.
DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO) . . . IF (%SST (&NAME 1 5) *EQ YES) + THEN(CALL PROGA)

If the length of the substring is shorter than the operand, the substring is padded with blanks for the comparison. For example:
DCL VAR(&NAME) TYPE(*CHAR) LEN(5) VALUE(YESNO) . . . IF (%SST(&NAME 1 3 ) *EQ YESNO) THEN(CALL PROG)

This condition is false because YESbb (where bb is two blanks) does not equal YESNO. v The value of the variable &A is placed into positions 1 through 10 of the local data area.
CHGVAR %SST(*LDA 1 10) &A

v If the concatenation of positions 1 through 3 of the local data area plus the constant XYZ is equal to variable &A, then PROCA is called. For example, if positions 1 through 3 of the local data area contain ABC and variable &A has a value of ABCXYZ, the test is true and PROCA is called.
IF (((%SST*LDA 1 3) *CAT XYZ) *EQ &A) THEN(CALLPRC PROCA)

v This procedure scans the character variable &NUMBER and changes any leading zeros to blanks. This can be used for simple editing of a field before displaying in a message.
DCL &NUMBER *CHAR LEN(5) DCL &X *DEC LEN(3 0) VALUE(1) . . LOOP:IF (%SST(&NUMBER &X 1) *EQ 0) DO CHGVAR (%SST(&NUMBER &X 1)) /* Blank out */ CHGVAR &X (&X + 1) /* Increment */ IF (&X *NE 4) GOTO LOOP ENDDO

The following procedure uses the substring built-in function to find the first sentence in a 50-character field &INPUT and to place any remaining text in a field &REMAINDER. It assumes that a sentence must have at least 2 characters, and no embedded periods. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL DCL DCL (&INPUT &REMAINDER) /* &INPUT *CHAR LEN(50) &REMAINDER *CHAR LEN(50) &X *INT /* INDEX SEARCH */ */

206

System i: Programming Control language

DCL &L *INT

/* REMAINING LENGTH */

DOFORL: DOFOR &X 3 50 IF (%SST(&INPUT &X 1) *EQ .) THEN(DO) CHGVAR &L (50-&X) CHGVAR &X (&X+1) CHGVAR &REMAINDER %SST(&INPUT &X &L) LEAVE ENDDO ENDDO ENDPGM

The procedure starts by checking the third position for a period. Note that the substring function checks &INPUT from position 3 to a length of 1, which is position 3 only (length cannot be zero). If position 3 is a period, the remaining length of &INPUT is calculated. The value of &X is advanced to the beginning of the remainder, and the remaining portion of &INPUT is moved to &REMAINDER. If position 3 is not a period, the procedure checks to see if it is at position 49. If so, it assumes that position 50 is a period and returns. If it is not at position 49, the procedure advances &X to position 4 and repeats the process. Related tasks Variables to use for specifying a list or qualified name on page 175 Variables can be used to specify a list or qualified name. Changing the value of a variable on page 177 You can change the value of a CL variable using the Change Variable (CHGVAR) command. Related reference Built-in functions for CL on page 106 Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions. Related information CL command finder If (IF) command Change Variable (CHGVAR) command

%SWITCH built-in function

The switch built-in function (%SWITCH) compares one or more of eight switches with the eight switch settings already established for the job and returns a logical value of 0 or 1. The initial values of the switches for the job are determined first by the Create Job Description (CRTJOBD) command; the default value is 00000000. You can change this if necessary using the SWS parameter on the Submit Job (SBMJOB), Change Job (CHGJOB), or JOB command; the default for these is the job description setting. Other high-level languages can also set job switches. If, in the comparison of your %SWITCH values against the job values, every switch is the same, a logical value of 1 (true) is returned. If any switch tested does not have the value indicated, the result is a 0 (false). The syntax of the %SWITCH built-in function is:
%SWITCH(8-character-mask)

The 8-character mask is used to indicate which job switches are to be tested, and what value each switch is to be tested for. Each position in the mask corresponds with one of the eight job switches in a job. Position 1 corresponds with job switch 1, position 2 with switch 2, and so on. Each position in the mask can be specified as one of three values: 0, 1, or X.
Control language

207

0 1 X

The corresponding job switch is to be tested for a 0 (off). The corresponding job switch is to be tested for a 1 (on). The corresponding job switch is not to be tested. The value in the switch does not affect the result of %SWITCH.

If %SWITCH(0X111XX0) is specified, job switches 1 and 8 are tested for 0s; switches 3, 4, and 5 are tested for 1s; and switches 2, 6, and 7 are not tested. If each job switch contains the value (1 or 0 only) shown in the mask, the result of %SWITCH is true 1. Switches can be tested in a CL procedure to control the flow of the procedure. This function is used in CL procedures with the If (IF) and Change Variable (CHGVAR) commands. Switches can be changed in a CL procedure by the Change Job (CHGJOB) command. For CL procedures, these changes take effect immediately. Related tasks Changing the value of a variable on page 177 You can change the value of a CL variable using the Change Variable (CHGVAR) command. Related reference Built-in functions for CL on page 106 Control language (CL) provides several built-in functions. Built-in functions are used in arithmetic, relational, or logical expressions. Related information CL command finder Change Job (CHGJOB) command Submit Job (SBMJOB) command Change Job Description (CHGJOBD) command Change Variable (CHGVAR) command %SWITCH with the IF command: On the If (IF) command, %SWITCH can be specified on the COND parameter as the logical expression to be tested. In the following example, 0X111XX0 is compared to the predetermined job switch setting:
IF COND(%SWITCH(0X111XX0)) THEN(GOTO C)

If job switch 1 contains 0, job switch 3 contains 1, job switch 4 contains 1, job switch 5 contains 1, and job switch 8 contains 0, the result is true and the procedure branches to the command having the label C. If one or more of the switches tested do not have the values indicated in the mask, the result is false, and the branch does not occur. In the following example, switches control conditional processing in two procedures. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
SBMJOB JOB(APP502) JOBD(PAYROLL) CMD(CALL APP502) SWS(11000000) PGM /* CONTROL */ IF (%SWITCH(11XXXXXX)) IF (%SWITCH(10XXXXXX)) IF (%SWITCH(01XXXXXX)) IF (%SWITCH(00XXXXXX)) ENDPGM CALLPRC CALLPRC CALLPRC CALLPRC PROCA PROCB PROCC PROCD

208

System i: Programming Control language

PGM /* PROCA */ CALLPRC TRANS IF (%SWITCH(1XXXXXXX)) CALLPRC CUS520 ELSE CALLPRC CUS521 ENDPGM

Related information If (IF) command %SWITCH with the Change Variable command: On the Change Variable (CHGVAR) command, you can specify %SWITCH to change the value of a logical variable. The value of the logical variable is determined by the results of comparing your %SWITCH settings with the job switch settings. If the result of the comparison is true, the logical variable is set to 1. If the result is false, the variable is set to 0. For instance, if the job switch is set to 10000001 and this procedure is processed, then the variable &A has a value of 1:
PGM DCL &A *LGL CHGVAR VAR(&A) VALUE(%SWITCH(10000001)) . . . ENDPGM

Related information Change Variable (CHGVAR) command

Monitor Message command

The Monitor Message (MONMSG) command is used to monitor for escape, notify, or status messages sent to the call stack of the procedure in which the MONMSG command is used. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. Escape messages are sent to CL procedures by the commands in the CL procedures and by the programs and procedures they call. These escape messages are sent to tell the procedures that errors were detected and requested functions were not performed. CL procedures can monitor for the arrival of escape messages, and you can specify through commands how to handle the messages. For example, if a CL procedure tries to move a data area that has been deleted, an object-not-found escape message is sent to the procedure by the Move Object (MOVOBJ) command. Using the MONMSG command, you can direct a procedure to take predetermined action if specific errors occur during the processing of the immediately preceding command. The MONMSG command has the following parameters:
MONMSG MSGID(message-identifier) CMPDTA(comparison-data) + EXEC(CL-command)

Each message that is sent for a specific error has a unique identifier. You can enter as many as 50 message identifiers on the MSGID parameter. (See the online help for messages and identifiers). The CMPDTA parameter allows even greater specification of error messages because you can check for a specific character string in the MSGDTA portion of the message. On the EXEC parameter, you can specify a CL command (such as a Call Program (CALL), Do (DO), or a Go To (GOTO)), which directs the procedure to perform error recovery. In the following example, the MONMSG command follows the Receive File (RCVF) command and, therefore, is only monitoring for messages sent by the RCVF command:
Control language

209

READLOOP:

EOF:

RCVF /* Read a file record */ MONMSG MSGID(CPF0864) EXEC(GOTO CMDLBL(EOF)) /* Process the file record */ GOTO CMDLBL(READLOOP) /* Get another record */ /* End of file processing */

The escape message, CPF0864, is sent to the procedures invocation queue when there are no more records in the file to read. Because the example specifies MSGID(CPF0864), the MONMSG monitors for this condition. When it receives the message, the GOTO CMDLBL(EOF) command is run. You can also use the MONMSG command to monitor for messages sent by any command in a CL procedure. The following example includes two MONMSG commands. The first MONMSG command monitors for the messages CPF0001 and CPF1999; these messages might be sent by any command run later in the procedure. When either message is received from any of the commands running in the procedure, control branches to the command identified by the label EXIT2. The second MONMSG command monitors for the messages CPF2105 and MCH1211. Because no command is coded for the EXEC parameter, these messages are ignored.
PGM DCL MONMSG MSGID(CPF0001 CPF1999) EXEC(GOTO EXIT2) MONMSG MSGID(CPF2105 MCH1211) . . . ENDPGM

Message CPF0001 states that an error was found in the command that is identified in the message itself. Message CPF1999, which can be sent by many of the debugging commands, such as Change Program Variable (CHGPGMVAR), states that errors occurred on the command, but it does not identify the command in the message. All error conditions monitored for by the MONMSG command with the EXEC parameter specified (CPF0001 or CPF1999) are handled in the same way at EXIT2, and it is not possible to return to the next sequential statement after the error. You can avoid this by monitoring for specific conditions after each command and branching to specific error correction procedures. All error conditions monitored for by the MONMSG command without the EXEC parameter specified (CPF2105 or MCH1211) are ignored, and procedure processing continues with the next command. If the error occurs when evaluating the expression on an IF command, the condition is considered false. In the following example, MCH1211 (divide by zero) could occur on the IF command. The condition would be considered false, and PROCA would be called.
IF(&A / &B *EQ 5) THEN(DLTF ABC) ELSE CALLPRC PROCA

If you code the MONMSG command at the beginning of your CL procedure, the messages you specify are monitored throughout the program, regardless of which command produces these messages. If the EXEC parameter is used, only the GOTO command can be specified. If the GOTO command is run in your program, the subroutine stack will be reset. You can specify the same message identifier on a procedure-level or a command-level MONMSG command. The command-level MONMSG commands take precedence over the procedure-level MONMSG commands. In the following example, if message CPF0001 is received on CMDB, CMDC is run. If message CPF0001 is received on any other command in the procedure, the procedure branches to EXIT2. If message CPF1999 is received on any command, including CMDB, the procedure branches to EXIT2.

210

System i: Programming Control language

PGM MONMSG MSGID(CPF0001 CPF1999) EXEC(GOTO EXIT2) CMDA CMDB MONMSG MSGID(CPF0001) EXEC(CMDC) CMDD EXIT2: ENDPGM

Because many escape messages can be sent to a procedure, you must decide which ones you want to monitor for and handle. Most of these messages are sent to a procedure only if there is an error in the procedure. Others are sent because of conditions outside the procedure. Generally, a CL procedure should monitor for those messages that pertain to its basic function and that it can handle appropriately. For all other messages, the i5/OS operating system assumes an error has occurred and takes appropriate default action. Related tasks Defining message descriptions on page 453 Predefined messages are stored in a message file. Messages on page 452 Messages are used to communicate between users and programs. Checking for the existence of an object on page 437 Before attempting to use an object in a program, check to determine if the object exists and if you have the authority to use it. Related information CL command finder Monitor Message (MONMSG) command

Retrieving values that can be used as variables

You can retrieve values, such as system values and job attributes, to use as variables in a procedure. Note that not every retrievable value is included. Related information CL command finder

Retrieving system values

A system value contains control information for the operation of certain parts of the system. IBM supplies several types of system values. For example, QDATE and QTIME are date and time system values, which you set when the i5/OS operating system is started. You can bring system values into your procedure and manipulate them as variables using the Retrieve System Value (RTVSYSVAL) command:
RTVSYSVAL SYSVAL(system-value-name) RTNVAR(CL-variable-name)

The RTNVAR parameter specifies the name of the variable in your CL procedure that is to receive the value of the system value. The type of the variable must match the type of the system value. For character and logical system values, the length of the CL variable must equal the length of the value. For decimal values, the length of the variable must be greater than or equal to the length of the system value. Related information System values Example: Retrieving QTIME system value:

Control language

211

In this example, QTIME is received and moved to a variable, which is then compared with another variable. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL VAR(&PWRDNTME) TYPE(*CHAR) LEN(6) VALUE(162500) DCL VAR(&TIME) TYPE(*CHAR) LEN(6) RTVSYSVAL SYSVAL(QTIME) RTNVAR(&TIME) IF (&TIME *GT &PWRDNTME) THEN(DO) SNDBRKMSG(Powering down in 5 minutes. Please sign off.) PWRDWNSYS OPTION(*CNTRLD) DELAY(300) RESTART(*NO) + IPLSRC(*PANEL) ENDDO ENDPGM

Related information System values Retrieving the QDATE system value into a CL variable: In many applications, you might want to use the current date in your procedure by retrieving the system value QDATE and placing it in a variable. You might also want to change the format of that date for use in your procedure. Note: By using the code examples, you agree to the terms of the Code license and disclaimer information on page 569. To convert the format of a date in a CL procedure, use the Convert Date (CVTDAT) command. The format for the system date is the system value QDATFMT. The included value of QDATFMT varies according to country or region. For example, 062488 is the MDY (monthdayyear) format for June 24 1988. You can change this format to the YMD, DMY, or the JUL (Julian) format. For Julian, the QDAY value is a 3-character value from 001 to 366. It is used to determine the number of days between two dates. You can also delete the date separators or change the character used as a date separator with the Convert Date (CVTDAT) command. The format for the Convert Date (CVTDAT) command is:
CVTDAT DATE(date-to-be-converted) TOVAR(CL-variable) + FROMFMT(old-format) TOFMT(new-format) + TOSEP(new-separators)

The DATE parameter can specify a constant or a variable to be converted. After the date has been converted, it is placed in the variable named on the TOVAR parameter. In the following example, the date in variable &DATE, which is formatted as MDY, is changed to the DMY format and placed in the variable &CVTDAT.
CVTDAT DATE(&DATE) TOVAR(&CVTDAT) FROMFMT(*MDY) TOFMT(*DMY) TOSEP(*SYSVAL)

The date separator remains as specified in the system value QDATSEP. The Convert Date (CVTDAT) command can be useful when creating objects or adding a member that uses a date as part of its name. For example, assume that a member must be added to a file using the current system date. Also, assume that the current date is in the MDY format and is to be converted to the Julian format.

212

System i: Programming Control language

PGM DCL &DATE6 *CHAR LEN(6) DCL &DATE5 *CHAR LEN(5) RTVSYSVAL QDATE RTNVAR(&DATE6) CVTDAT DATE(&DATE6) TOVAR(&DATE5) ADDPFM LIB1/FILEX MBR(MBR *CAT . . . ENDPGM

TOFMT(*JUL) &DATE5)

TOSEP(*NONE)

If the current date is 5 January 1988, the added member would be named MBR88005. Remember the following when converting dates: v The length of the value in the DATE parameter and the length of the variable on the TOVAR parameter must be compatible with the date format. The length of the variable on the TOVAR parameter must be at least: v 1. For Non-Julian Dates possessing 2 digit years a. Use 6 characters when using no separators.
July 28, 1978 would be written as 072878.

b. Use 8 characters when using separators.

July 28, 1978 would be written as 07-28-78.

2. For Non-Julian Dates with 4digit years a. Use 8 characters when using no separators.
July 28, 1978 would be written as 07281978.

b. Use 10 characters when using separators.

July 28, 1978 would be written as 07-28-1978.

3. For Julian dates with 2digit years a. Use 5 characters when using no separators.
December 31, 1996 would be written as 96365.

b. Use 6 characters when using separators.

December 31, 1996 would be written as 96-365.

4. For Julian dates with 4digit years, a. 7 characters are required when no separators are used.
February 4, 1997 would be written as 1997035.

b. 8 characters are required when separators are used.

February 4, 1997 would be written as 1997-035.

Error messages are sent for converted characters that do not fit in the variable. If the converted date is shorter than the variable, it is padded on the right with blanks. v In every date format except Julian, the month and day are 2-byte fields no matter what value they contain. The year can be either 2-byte or 4-byte fields. All converted values are right-aligned and, when necessary, padded with leading zeros. v In the Julian format, day is a 3-byte field, and year is a 2-byte or 4-byte field. All converted values are right-aligned and, when necessary, padded with leading zeros. The following is an alternative program that uses the ILE bindable API, Get Current Local Time (CEELOCT), to convert a date to Julian format. To create this program, you must use the Create Bound Control Language Program (CRTBNDCL) command alone, or the Create Control Language Module (CRTCLMOD) command and the Create Program (CRTPGM) command together.

Control language

213

PGM DCL DCL DCL DCL DCL

LEN(4) LEN(5) VALUE(YYDDD) LEN(5) 8 /* Seconds from CEELOCT 23 /* Gregorian date from CEELOCT /* CALLPRC PRC(CEELOCT) /* Get current date and time PARM(&LILDATE /* Date in Lilian format &SECONDS /* Seconds field will not be used &GREG /* Gregorian field will not be used *OMIT) /* Omit feedback parameter /* so exceptions are signalled CALLPRC PRC(CEEDATE) + PARM(&LILDATE &PICTSTR &JULDATE *OMIT) LIB1/FILEX /* Todays date /* How to format /* Julian date *CAT &JULDATE) */ + */ + */ +

&LILDATE &PICTSTR &JULDATE &SECONDS &GREG

*INT *CHAR *CHAR *CHAR *CHAR

*/ */ */ */ */ */ */ */ */

+ + + + +

ADDPFM ENDPGM

MBR(MBR

Related information Application Programming Interfaces (API)

Retrieving configuration source

Using the Retrieve Configuration Source (RTVCFGSRC) command, you can generate CL command source for creating existing configuration objects and place the source in a source file member. The CL command source that is generated can be used for the following purposes: v Moving configurations from system to system v Maintaining on-site configurations v Saving configurations (without using SAVSYS) Related information Retrieve Configuration Source (RTVCFGSRC) command

Retrieving configuration status

Using the Retrieve Configuration Status (RTVCFGSTS) command, you can give applications the capability to retrieve configuration status from three configuration objects: line, controller, and device. The Retrieve Configuration Status (RTVCFGSTS) command can be used in a CL procedure to check the status of a configuration description. Related information Retrieve Configuration Status (RTVCFGSTS) command

Retrieving network attributes

Using the Retrieve Network Attributes (RTVNETA) command, you can retrieve the network attributes of the system. These attributes can be changed using the Change Network Attributes (CHGNETA) command and displayed using the Display Network Attributes (DSPNETA) command. Related information Retrieve Network Attributes (RTVNETA) command Change Network Attributes (CHGNETA) command Display Network Attributes (DSPNETA) command

214

System i: Programming Control language

Retrieve Network Attributes (QWCRNETA) API Example: Using the Retrieve Network Attributes command: This example shows how to retrieve network attributes by using the Retrieve Network Attributes (RTVNETA) command. In the following example, the default network output queue and the library that contains it are retrieved, changed to QGPL/QPRINT, and later changed back to the previous value. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.
PGM DCL VAR(&OUTQNAME) TYPE(*CHAR) LEN(10) DCL VAR(&OUTQLIB) TYPE(*CHAR) LEN(10) RTVNETA OUTQ(&OUTQNAME) OUTQLIB(&OUTQLIB) CHGNETA OUTQ(QGPL/QPRINT) . . . CHGNETA OUTQ(&OUTQLIB/&OUTQNAME) ENDPGM

Retrieving job attributes

To retrieve the job attributes and place their values in a CL variable to control your applications, use the Retrieve Job Attributes (RTVJOBA) command. With this command you can retrieve all job attributes or any combination of them. In the following CL procedure, a Retrieve Job Attributes (RTVJOBA) command retrieves the name of the user who called the procedure.
PGM /* ORD410C Order entry program */ DCL &CLKNAM TYPE(*CHAR) LEN(10) DCL &NXTPGM TYPE(*CHAR) LEN(3) . . . RTVJOBA USER(&CLKNAM) BEGIN: CALL ORD410S2 PARM(&NXTPGM &CLKNAM) /* Customer prompt */ IF (&NXTPGM *EQ END) THEN(RETURN) . . .

The variable &CLKNAM, in which the user name is to be passed, is first declared using a DCL command. The Retrieve Job Attributes (RTVJOBA) command follows the declare commands. When the program ORD410S2 is called, two variables, &NXTPGM and &CLKNAM, are passed to it. &NXTPGM is passed as blanks but could be changed by ORD410S2. Related information Retrieve Job Attributes (RTVJOBA) command Example: Using the Retrieve Job Attributes command: This example shows how to retrieve job attributes by using the Retrieve Job Attributes (RTVJOBA) command.

Control language

215

Assume in the following CL procedure, an interactive job submits a program including the CL procedure to batch. A Retrieve Job Attributes (RTVJOBA) command retrieves the name of the message queue to which the jobs completion message is sent, and uses that message queue to communicate with the user who submitted the job.
PGM DCL &MSGQ *CHAR 10 DCL &MSGQLIB *CHAR 10 DCL &MSGKEY *CHAR 4 DCL &REPLY *CHAR 1 DCL &ACCTNO *CHAR 6 . . . RTVJOBA SBMMSGQ(&MSGQ) SBMMSGQLIB(&MSGQLIB) IF (&MSGQ *EQ *NONE) THEN(DO) CHGVAR &MSGQ QSYSOPR CHGVAR &MSGQLIB QSYS ENDDO . . . IF (. . . ) THEN(DO) SNDMSG:SNDPGMMSG MSG(Account number *CAT &ACCTNO *CAT is + not valid. Do you want to cancel the update + (Y or N)?) TOMSGQ(&MSGQLIB/&MSGQ) MSGTYPE(*INQ) + KEYVAR(&MSGKEY) RCVMSG MSGQ(*PGMQ) MSGTYPE(*RPY) MSGKEY(&MSGKEY) + MSG(&REPLY) WAIT(*MAX) IF (&REPLY *EQ Y) THEN(RETURN) ELSE IF (&REPLY *NE N) THEN(GOTO SNDMSG) ENDDO . . .

Two variables, &MSGQ and &MSGQLIB, are declared to receive the name and library of the message queue to be used. The Retrieve Job Attributes (RTVJOBA) command is used to retrieve the message queue name and library name. Because it is possible that a message queue is not specified for the job, the message queue name is compared to the value *NONE. If the comparison is equal, no message queue is specified, and the variables are changed so that message queue QSYSOPR in library QSYS is used. Later in the procedure, when an error condition is detected, an inquiry message is sent to the specified message queue and the reply is received and processed. Some of the other possible uses of the Retrieve Job Attributes (RTVJOBA) command are: v Retrieve one or more of the job attributes (such as output queue, library list) so that they can be changed temporarily and later restored to their original values. v Retrieve one or more of the job attributes for use in the Submit Job (SBMJOB) command, so that the submitted job will have the same attributes as the submitting job.

Retrieving user profile attributes

Using the Retrieve User Profile (RTVUSRPRF) command, you can retrieve the attributes of a user profile (except for the password) and place their values in CL variables to control your applications. On this command, you can specify either the 10-character user profile name or *CURRENT. You can also monitor for escape messages after running the Retrieve User Profile(RTVUSRPRF) command. Related information Retrieve User Profile (RTVUSRPRF) command Example: Using the Retrieve User Profile command:

216

System i: Programming Control language

This example shows how to retrieve user profile information by using the Retrieve User Profile (RTVUSRPRF) command. In the following CL procedure, a Retrieve User Profile(RTVUSRPRF) command retrieves the name of the user who called the procedure and the name of a message queue to which to send messages for that user:
DCL &USR *CHAR 10 DCL &USRMSGQ *CHAR 10 DCL &USRMSGQLIB *CHAR 10 . . . RTVUSRPRF USRPRF(*CURRENT) RTNUSRPRF(&USR) + MGSQ(&USRMSGQ) MSGQLIB(&USRMSGQLIB)

The following information is returned to the procedure: v &USR contains the user profile name of the user who called the program. v &USRMSGQ contains the name of the message queue specified in the user profile. v &USRMSGQLIB contains the name of the library containing the message queue associated with the user profile.

Retrieving member description information

Using the Retrieve Member Description (RTVMBRD) command, you can retrieve information about a member of a database file for use in your applications. Related information Retrieve Member Description (RTVMBRD) command Example: Using the Retrieve Member Description command: This example shows how to retrieve member description information by using the Retrieve Member Description (RTVMBRD) command. In the following CL procedure, a Retrieve User Profile Attributes (RTVUSRPRF) command retrieves the description of a specific member. Assume a database file called MFILE exists in the current library (MYLIB) and contains 3 members (AMEMBER, BMEMBER, and CMEMBER).
DCL &LIB TYPE(*CHAR) LEN(10) DCL &MBR TYPE(*CHAR) LEN(10) DCL &SYS TYPE(*CHAR) LEN(4) DCL &MTYPE TYPE(*CHAR) LEN(5) DCL &CRTDATE TYPE(*CHAR) LEN(13) DCL &CHGDATE TYPE(*CHAR) LEN(13) DCL &TEXT TYPE(*CHAR) LEN(50) DCL &NBRRCD TYPE(*DEC) LEN(10 0) DCL &SIZE TYPE(*DEC) LEN(10 0) DCL &USEDATE TYPE(*CHAR) LEN(13) DCL &USECNT TYPE(*DEC) LEN(5 0) DCL &RESET TYPE(*CHAR) LEN(13) . . . RTVMBRD FILE(*CWeb siteIB/MYFILE) MBR(AMEMBER *NEXT) + RTNLIB(&LIB) RTNSYSTEM(&SYS) RTNMBR(&MBR) + FILEATR(&MTYPE) CRTDATE(&CRTDATE) TEXT(&TEXT) + NBRCURRCD(&NBRRCD) DTASPCSIZ(&SIZE) USEDATE(&USEDATE) + USECOUNT(&USECNT) RESETDATE(&RESET)

The following information is returned to the procedure: v The current library name (MYLIB) is placed into the CL variable name &LIB.

Control language

217

v The system that MYFILE was found on is placed into the CL variable name &SYS (*LCL means the file was found on the local system, and *RMT means the file was found on a remote system). v The member name (BMEMBER), since BMEMBER is the member immediately after AMEMBER in a name ordered member list (*NEXT), is placed into the CL variable named &MBR. v The file attribute of MYFILE is placed into the CL variable named &MTYPE (*DATA means the member is a data member, and *SRC means the file is a source member). v The creation date of BMEMBER is placed into the CL variable called &CRTDATE. v The text used to describe BMEMBER is placed into the CL variable called &TEXT. v The current number of records in BMEMBER is placed into the CL variable called &NBRRCD. v The size of BMEMBERs data space (in bytes) is placed into the CL variable called &SIZE. v The date that BMEMBER was last used is placed into the CL variable called &USEDATE. v The number of days that BMEMBER has been used is placed into the CL variable called &USECNT The start date of this count is the value placed into the CL variable called &RESET.

Compiling CL procedures
A CL source procedure must be compiled into a module and bound into a program before it can be run. To create a CL program in one step, you can use the Create Bound Control Language Program (CRTBNDCL) command and create a bound program with one module. You can also create a module with the Create Control Language Module (CRTCLMOD) command. The module must then be bound into a program or service program using the Create Program (CRTPGM) or Create Service Program (CRTSRVPGM) command. The following example creates the module ORD040C and places it in library DSTPRODLB:
CRTCLMOD MODULE(DSTPRODLB/ORD040C) SRCFILE(QCLSRC) TEXT(Order dept general menu program)

The source commands for ORD040C are in the source file QCLSRC, and the source member name is ORD040C. By default, a compiler listing is created. On the Create Bound Control Language Program (CRTBNDCL) command, you can specify listing options and whether the program should operate under the program owners user profile. A program can run using either the owners user profile or the users user profile. CL procedures and programs are created using options on the Programming Development Manager (PDM) menu or the Programmer Menu so the Create Control Language Module (CRTCLMOD) command or Create Bound Control Language Program (CRTBNDCL) command does not have to be directly entered. Related information CL command finder Create Program (CRTPGM) command Create Bound CL Program (CRTBNDCL) command Create CL Module (CRTCLMOD) command Create Service Program (CRTSRVPGM) command

Logging CL procedure commands

You can specify that most CL commands run in a CL procedure be written (logged) to the job log.

218

System i: Programming Control language

This can be done by specifying one of the following values on the LOG parameter on the Create Control Language Module (CRTCLMOD) command or the Create Bound Control Language Program (CRTBNDCL) command when the procedure is compiled: *JOB This default value indicates that logging is to occur when the jobs logging option is on. The option is initially set for no logging, but it can be changed by the LOGCLPGM parameter on the Change Job (CHGJOB) command. Therefore, if you create the module or program with this value, you can alter the logging option for each job or several times within a job. This value indicates that logging is to occur each time the CL procedure is run. It cannot be changed by the CHGJOB command. This value indicates that no logging is to occur. It cannot be changed by the CHGJOB command.

*YES *NO

Because these values are part of the Create Control Language Module (CRTCLMOD) and the Create Bound Control Language Program (CRTBNDCL) commands, you must recompile the module or program to change them. When you specify logging, you should use the Remove Message (RMVMSG) command with care in order not to remove any logged commands from the job log. If you specify CLEAR(*ALL) on the RMVMSG command, any commands logged before running the RMVMSG command do not appear in the job log. This affects only the CL procedure containing the RMVMSG command and does not affect any logged commands for the preceding or following recursion levels. Not all commands are logged to the job log. The following list is about commands that are not logged. | CALLPRC | DCL
DO DOWHILE ENDPGM GOTO LEAVE PGM SUBR CALLSUBR DCLF DOFOR ELSE ENDSELECT IF MONMSG RTNSUBR WHEN CHGVAR DCLPRCOPT DOUNTIL ENDDO ENDSUBR ITERATE OTHERWISE SELECT

| |

If the logging option is on, logging messages are sent to the CL procedures message queue. If the CL procedure is running interactively, and the message level on the jobs LOG parameter is set to 4, you can press F10 (Display detail messages) to view the logging of all commands. You can print the log if the message level is 4 and you specify *PRINT when you sign off. The log includes the time, program and procedure names, message texts, and command names. Command names are qualified as they are on the original source statement. Command parameters are also logged; if the parameter information is a CL variable, the contents of the variable are printed (except for the RTNVAL parameter). Logging of commands affects performance. Related concepts Job log on page 527 Each job has an associated job log. Related information CL command finder Create CL Module (CRTCLMOD) command Create Bound CL Program (CRTBNDCL) command Change Job (CHGJOB) command
Control language

219

Remove Message (RMVMSG) command

CL module compiler listings

When you create a CL module, you can create various types of listings using the OPTION and OUTPUT parameters on the Create Control Language Module (CRTCLMOD) command. The OPTION parameter values and their meanings are: v *GEN or *NOGEN Whether a module is to be created (*GEN is the default). v *XREF or *NOXREF Whether a listing of cross-references to variables and data references in the source input is to be produced (*XREF is the default). The OUTPUT parameter values and their meanings are: v *PRINT - print listing v *NONE - no compiler listing The listing created by specifying the OUTPUT parameter is called a compiler listing. The following example is about compiler listing. The callout numbers refer to descriptions following the listing. Note: By using the code example, you agree to the terms of the Code license and disclaimer information on page 569.

220

System i: Programming Control language

1 2 5722SS1 V5R3M0 041231 Control Language MYLIB/DUMPER SYSNAME 05/06/00 [Link] Module . . . . . . . . . . . . . . . . . . . . : DUMPERR Library . . . . . . . . . . . . . . . . . . : MYLIB Source file . . . . . . . . . . . . . . . . . : QCLSRC Library . . . . . . . . . . . . . . . . . . : MYLIB Source member name . . . . . . . . . . . . . : DUMPERR 05/06/94 [Link] 4 Source printing options . . . . . . . . . . . : *XREF *NOSECLVL *NOEVENTF Module logging . . . . . . . . . . . . . . . : *JOB Replace module object . . . . . . . . . . . . : *YES Target release . . . . . . . . . . . . . . . : V5R3M0 Authority . . . . . . . . . . . . . . . . . . : *LIBCRTAUT Sort sequence . . . . . . . . . . . . . . . . : *HEX Language identifier . . . . . . . . . . . . . : *JOBRUN Text . . . . . . . . . . . . . . . . . . . . : Test program Optimization . . . . . . . . . . . . . . . . : *NONE Debugging view . . . . . . . . . . . . . . . : *STMT Enable performance collection . . . . . . . . : *PEP Compiler . . . . . . . . . . . . . . . . . . : IBM i5/OS Control Language Compiler 5 6 Control Language Source SEQNBR *...+... 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 ...+... 8 ...+... 9 ...+. DATE 8 100- PGM 05/06/94 200- DCL &ABC *CHAR 10 VALUE(THIS) 05/06/94 300- DCL &XYZ *CHAR 10 VALUE(THAT) 7 05/06/94 400- DCL &MNO *CHAR 10 VALUE(OTHER) 05/06/94 500- CRTLIB LB(LARRY) 05/06/94 * CPD0043 30 Keyword LB not valid for this command. 9 600- DLTLIB LIB(MOE 05/06/94 * CPD0013 30 A matching parenthesis not found. 700- MONMSG CPF0000 EXEC(GOTO ERR) 05/06/94 800- ERROR: 05/06/94 900- CHGVAR &ABC ONE 05/06/94 1000- CHGVAR &XYZ TWO 05/06/94 1100- CHGVAR &MNO THREE 05/06/94 1200- DMPCLPGM 05/06/94 1300- ENDPGM 05/06/94 * * * * * E N D O F S O U R C E * * * * * 5722SS1 V5R3M0 040201 Control Language MYLIB/DUMPER SYSNAME 05/06/00 [Link] Cross Reference Declared Variables Name Defined Type Length References &ABC 200 *CHAR 10 900 &MNO 400 *CHAR 10 1100 10 &XYZ 300 *CHAR 10 1000 Defined Labels Label Defined References 11 ERR ****** 700 * CPD0715 30 Label ERR does not exist. ERROR 800 * * * * * E N D O F C R O S S R E F E R E N C E * * * * * 5722SS1 V5R3M0 040201 Control Language MYLIB/DUMPER SYSNAME 05/06/04 [Link] Message Summary Severity Total 0-9 10-19 20-29 30-39 40-49 50-59 60-69 70-79 80-89 90-99 12 3 0 0 0 3 0 0 0 0 0 0 Module DUMPERR not created in library MYLIB. Maximum error severity 30. 13 * * * * * E N D O F M E S S A G E S U M M A R Y * * * * * * * * * * E N D O F C O M P I L A T I O N * * * * *

3 Page 1

Page 2

Page 3

Title: 1 2 3 Prolog: 4 The parameter values specified (or defaults if not specified) on the Create Control Language Module (CRTCLMOD) command. If the source is not in a database file, the member name, date, and time are omitted. The name of the compiler. The program number, release, modification level and date of the i5/OS operating system. The date and time of the compiler run. The page number in the listing.

5 Source: 6

The sequence numbers of lines (records) in the source. A dash following a sequence number indicates that a source statement begins at that sequence number. The absence of a dash indicates that a statement is the continuation of the previous statement. Comments between source statements are handled like any other source statement and have sequence numbers.
Control language

221

7 8 9

The source statements. The last date the source statement was changed or added. If the source is not in a database file, or the dates have been reset using RGZPFM, the date is omitted. If an error is found during compilation and can be traced to a specific source statement, the error message is printed immediately following the source statement. An asterisk (*) indicates the line contains an error message. The line contains the message identifier, severity, and the text of the message.

Cross-References: 10 The symbolic variable table is a cross-reference listing of the variables validly declared in the program. The table lists the variable, the sequence number of the statement where the variable is declared, the variables attributes, and the sequence numbers of statements that refer to the variable. The label table is a cross-reference listing of the labels validly defined in the program. The table lists the label, the sequence number of the statement where the label is defined, and the sequence numbers of statements that refer to the label.

11

Messages: This section is not included in the sample listing because no general error messages were issued for the sample module. If there were general error messages for this module, this section would contain, for each message, the message identifier, the severity, and the message. Message Summary: 12 13 A summary of the number of messages issued during compilation. The total number is given along with totals by severity. A completion message is printed following the message summary.

The title, prologue, source, and message summary sections are always printed for the *SOURCE option. The cross-reference section is printed if the *XREF option is specified. The message section is printed only if general errors are found. Related concepts Common compilation errors The types of errors that are detected at compile time include syntax errors, references to variables and labels not defined, and missing statements. Related information Create CL Module (CRTCLMOD) command

Common compilation errors

The types of errors that are detected at compile time include syntax errors, references to variables and labels not defined, and missing statements. In the compiler listing of a module, an error condition that relates directly to a specific command is listed after that command. Messages that do not relate to a specific command but are more general in nature are listed in a messages section of the listing, not inline with source statements. The following types of errors stop the procedure from being created (severity codes are ignored). v Value errors v Syntax errors v Errors related to dependencies between parameters within a command v Errors detected during validity checking

222

System i: Programming Control language

Even after an error that stops the procedure from being created is encountered, the compiler continues to check the source for errors. This lets you see and correct as many errors as possible before you try to create the module or program again. Related reference CL module compiler listings on page 220 When you create a CL module, you can create various types of listings using the OPTION and OUTPUT parameters on the Create Control Language Module (CRTCLMOD) command.

Obtaining a CL procedure dump

You can obtain a CL procedure dump during procedure processing. The CL procedure dump consists of a listing of all messages on the procedures message queue and the values of all variables used in the procedure. This information may be useful in determining the cause of a problem affecting procedure processing. To obtain a CL procedure dump, complete one of the following tasks: v Run the Dump CL Program (DMPCLPGM) command. This command can only be used in a CL procedure and does not end the CL procedure. v Enter D in response to inquiry message CPA0701 or CPA0702. The system sends this message whenever it receives an unmonitored escape message from a CL procedure. If the program is running in an interactive job, the system sends the message to the jobs external message queue. If the program is running as a batch job, the system sends the message to the system operator message queue, QSYSOPR. v Specify INQMSGRPY(*SYSRPYL) for the job. The IBM-supplied system reply list specifies a reply of D for message CPA0702 or CPA0701. The system will print a dump if it receives one of the inquiry messages. v Change the default reply for message CPA0701 or CPA0702 from C (cancel program) to D (dump procedure). This prints a procedure dump whenever a function check occurs in a CL procedure. To change the default, enter the following command:
CHGMSGD MSGID(CPA0702) MSGF(QCPFMSG) DFT(D)

Note: The security officer, or another user with update authority to the QCPFMSG file, must enter the CHGMSGD command. Changing the message default causes a dump to be printed under any of the following conditions: v The system operator message queue is in default mode and the message is sent from a batch job. v The display station user presses the Enter key without typing a response, causing the message default to be used. v INQMSGRPY(*DFT) is specified for the job.

Control language

223

1 5722SS1 V5R3M0 040201

Control Language

MYLIB/DUMPER

SYSNAME 05/06/00 [Link] Page 1

Job name . . . . . . . . : DSP043 User name . . . . . . : SMITH 3 Job number . . . . . . : 01329 3 Program name . . . . . . : DUMP4 Library . . . . . . . : MYLIB4 Statement . . . . . . . : 1200 5 Module name . . . . . . : DUMP Procedure name . . . : DUMP Messages Time 110503 110503 Message 6 ID CPC2102 CPF2110 Sev 00 40 Message Type COMP ESC From Text Program Library LARRY created. QLICRLIB Library MOE not found. QLICLLIB Variables 7 Variable &ABC &XYZ Type *CHAR *CHAR Length 10 10 * * * * * Value *...+....1....+....2....+ ONE TWO E N D O F D U M P Value in Hexadecimal * . . . + . . . . 1 . . . . + . . . . 2 . . . . + D6D5C540404040404040 E3E6D640404040404040 * * * * * To Inst *N *N Program DUMP DUMP Inst *N *N

1 2 3 4 5 6

The program number, release, modification level and date of the i5/OS operating system. The date and time the dump was printed. The fully qualified name of the job in which the procedure was running. The name and library of the program. The number of the statement running when the dump was taken. If the command is a nested command, the statement number is that of the outer command. Each message on the call message queue, including the time the message was sent, message ID, severity, type, text, sending program and instruction number, and receiving program and instruction number. All variables declared in the procedure, including variable name, type, length, value, and hexadecimal value. If a decimal variable contains decimal data that is not valid, the character and hexadecimal values are printed as *CHAR variables. If the value for the variable cannot be located, *NOT ADDRESSABLE is printed. This can occur if the CL procedure is used in a command processing program for a command that has a parameter with either TYPE(*NULL) or PASSVAL(*NULL) specified, or if RTNVAL(*YES) was specified for the parameter and a return variable is not coded on the command. If a variable is declared as TYPE(*LGL), it is shown on the dump as *CHAR with a length of 1. Related information Controlling the default reply to the query governor inquiry message Dump CL Program (DMPCLPGM) command

Displaying module attributes

To display the attributes of a module, use the Display Module (DSPMOD) command. The information displayed or printed can be used to determine the options specified on the command used to create the module. Related information Display Module (DSPMON) command

Displaying program attributes

To display the attributes of a program, use the Display Program (DSPPGM) command. The information displayed or printed can be used to determine the options specified on the command used to create the program.

224

System i: Programming Control language

You can use the Display Program (DSPPGM) command to display the attributes of a program. To retrieve some of the attributes (such as program type, source member, text, creation date) into CL variables, you can use the Display Object Description (DSPOBJD) command to build an output file. The system can then read a CL procedure or program that uses the Declare File (DCLF) and Receive File (RCVF) commands. To access other attributes of the DSPPGM command (such as USRPRF), you can use the Retrieve program information (QCLRPGMI) API. Related information Display Program (DSPPGM) command

Return code summary

A return code can be returned using the (RTNCDE) parameter on the Retrieve Job Attributes (RTVJOBA) command . The return code is a 5-digit decimal value with no decimal positions (12345. for example). The decimal value indicates the status of called programs. CL programs do not set the return code. However, you can retrieve the current value of the return code as set by another program in a CL program. You can do this by using the RTNCDE parameter of the Retrieve Job Attributes (RTVJOBA) command. The following list summarizes the return codes used by languages supported on the i5/OS operating system: v RPG IV programs The return codes sent by the RPG IV compiler are: 0 When the program is created

2 When the program is not created The return codes sent by running RPG IV programs are: 0 1 2 When a program is started, or by the CALL operation before a program is called When a program ends with LR set on When a program ends with an error (response of C, D, F, or S to an inquiry message)

3 When a program ends because of a halt indicator (H1-H9) RPG IV return codes are tested only after a CALL: 0 or 1 indicate no error 3 gives an RPG IV status code of 231 Any other value gives an RPG IV status code 202 (call ended in error) The return code cannot be tested directly by the user in the RPG IV program. v ILE COBOL and OPM COBOL programs The return codes sent by running COBOL programs are: 0 2 By each CALL statement before a program is called

When a program receives a function check (CPF9999) or the generic I/O exception handler gets control and there is no applicable USE procedure COBOL programs cannot retrieve these return codes. For OPM COBOL, a return code value of 2 sends message LBE9001. For ILE COBOL, a return code value of 2 sends message CEE9001. v ILE C programs The current value of the integer return code is returned by the last ILE C return statement in an ILE C program. Related information Retrieve Job Attributes (RTVJOBA) command Reclaim Resources (RCLRSC) command
Control language

225

Compiling source programs for a previous release

The Create Control Language Program (CRTCLPGM) command allows you to compile CL source programs to use on a previous release by using the target release (TGTRLS) parameter. The TGTRLS parameter specifies on which release of the i5/OS licensed program the CL program object created intends to run. You can specify *CURRENT, *PRV, or a specific release level. A CL program compiled with TGTRLS(*CURRENT) runs only on the current release or later releases of the operating system. A CL program compiled with a specified TGTRLS value other than *CURRENT can run on the specified release value and on later releases. Related information Create CL Program (CRTCLPGM) command