Loading…

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

Like this document? Why not share!

Master ol20

on

  • 1,411 views

LAVORO IBM I

LAVORO IBM I

Statistics

Views

Total Views
1,411
Views on SlideShare
1,411
Embed Views
0

Actions

Likes
0
Downloads
17
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Master ol20 Master ol20 Document Transcript

  • V5.4cover Front cover Control Language Programming for IBM i (Course code OL20) Student Notebook ERC 9.0
  • Student NotebookTrademarksIBM® is a registered trademark of International Business Machines Corporation.The following are trademarks of International Business Machines Corporation in the UnitedStates, or other countries, or both:AIX® AS/400® C/400®DB2® i5/OS® Integrated Language Environment®iSeries® Language Environment® Notes®OS/400® Power Systems™ Power Systems Software™Rational® Redbooks® RPG/400®System i® WebSphere®Adobe is either a registered trademark or a trademark of Adobe Systems Incorporated inthe United States, and/or other countries.Intel and Pentium are trademarks or registered trademarks of Intel Corporation or itssubsidiaries in the United States and other countries.Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc.in the United States, other countries, or both.Windows is a trademark of Microsoft Corporation in the United States, other countries, orboth.Other product and service names might be trademarks of IBM or other companies.August 2010 editionThe information contained in this document has not been submitted to any formal IBM test and is distributed on an “as is” basis withoutany warranty either express or implied. The use of this information or the implementation of any of these techniques is a customerresponsibility and depends on the customer’s ability to evaluate and integrate them into the customer’s operational environment. Whileeach item may have been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results willresult elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. © Copyright International Business Machines Corporation 1997, 2010.This document may not be reproduced in whole or in part without the prior written permission of IBM.Note to U.S. Government Users — Documentation related to restricted rights — Use, duplication or disclosure is subject to restrictionsset forth in GSA ADP Schedule Contract with IBM Corp.
  • V5.4.0.1 Student NotebookTOC Contents Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Course description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii Agenda . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Unit 1. Class administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 CL programming for IBM i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 Course objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6 Agenda (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7 Agenda (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 Introductions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 Unit 2. Basic CL programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2.1. CL programming concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 CL programming concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Review of IBM i CL programming concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5 Prerequisite review (1 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6 Object identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7 Prerequisite review (2 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8 In which library is an object created? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9 Prerequisite review (3 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10 Finding an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11 Prerequisite review (4 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-12 Library list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-13 Prerequisite review (5 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-15 ?DSPOBJD OR DSPOBJD F4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16 Choices = F11 => keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-17 Prerequisite review (6 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-18 Help key: Additional information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-19 Prerequisite review (7 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-20 Prerequisite review (8 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-21 Creating and calling a CL program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-22 Prerequisite review (9 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-23 Prerequisite review (10 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-24 Prerequisite review (11 of 11) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-25 Batch and interactive jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-26 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-27 2.2. Basic CL programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-29 ©Copyright IBM Corp. 1997, 2010 Contents iii Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Basic CL programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-30 Reference manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-31 Control language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-32 CL commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-34 CL command syntax (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-36 CL command syntax (2 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-37 CL command syntax (3 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-38 CL command syntax (4 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-39 Coding rules (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-40 Coding rules (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-41 CL program structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-42 Declare CL variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-44 Declare CL variables examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-45 Declaring a display file in a CL program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-47 Using a display file in a CL program: Method one . . . . . . . . . . . . . . . . . . . . . . . . .2-48 Using a display file in a CL program: Method two . . . . . . . . . . . . . . . . . . . . . . . . .2-49 Display file operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-50 CHGVAR: Arithmetic calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-51 CHGVAR: Conversion between *CHAR and *DEC data types . . . . . . . . . . . . . . .2-52 Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-53 Data type conversion and concatenation example . . . . . . . . . . . . . . . . . . . . . . . . .2-54 Conditional execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-55 Relational and logical expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-56 IF examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-57 DO group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-58 Nested IF statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-59 PGMB and/or PGMC and/or PGMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-60 PGMB or PGMC or PGMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-61 Using the SELECT command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-62 Branching within a program: GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-64 Using the DOUNTIL and DOWHILE commands . . . . . . . . . . . . . . . . . . . . . . . . . .2-65 Using the DOFOR command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-67 Using the ITERATE command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-69 Using the LEAVE command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-71 Branching inside a program: CALLSUBR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-72 Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-74 Branching outside a program: TFRCTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-76 Communicating data to a program with CALL . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-77 HLL and CL programs may call each other . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-792.3. i application development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-81 i application development tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-82 IBM Rational Developer for Power Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-83 Rational support for i 7.1 and beyond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-84 Rational Developer for Power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-85 WDS/RDi 7.5/RDP 7.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-86 Tool choices: Editors (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-89 Tool choices: Editors (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-91 What is RDi/RDP/RSE? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2-92iv CL Programming for IBM i ©Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4.0.1 Student NotebookTOC LPEX editor interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-93 SEU: Similar features, prompting CL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-95 Multiple edit windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-96 Program generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-97 LPEX editor: Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98 LPEX editor summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-99 Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-100 Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-101 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-103 Unit 3. Program creation and debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 3.1. Creating program objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3 Creating program objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 OPM versus ILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5 Create Bound CL Program (CRTBNDCL) (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 Create Bound CL Program (CRTBNDCL) (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . 3-8 Declare Processing Options (DCLPRCOPT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-9 Create CL Program (CRTCLPGM) (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11 Create CL Program (CRTCLPGM) (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13 CL compile listing (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-14 CL compile listing (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15 CL compile listing (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16 Message severity codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17 3.2. Debugging CL programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19 Debugging CL programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20 Debugging a compiled program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-21 Before beginning a debug session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-22 Debug procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-24 Start Debug (STRDBG) (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25 Start Debug (STRDBG) (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28 Display Module Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30 Debug command examples: Valid during program execution . . . . . . . . . . . . . . . . 3-32 Display module source function keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33 IBM i: Debug commands (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-36 IBM i: Debug commands (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-37 Client debug tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-38 Integrated debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39 Starting the debug server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40 Start from RSE/LPEX editor: Interactive application . . . . . . . . . . . . . . . . . . . . . . . 3-41 3.3. Additional testing facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-43 Additional testing facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-44 Retrieve CL program source: RTVCLSRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-45 Example of source from RTVCLSRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-46 A program dump is a valuable debugging tool . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-47 Requesting a program dump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-48 STRISDB, STRSRVJOB, TRCJOB and STRTRC . . . . . . . . . . . . . . . . . . . . . . . . 3-49 ©Copyright IBM Corp. 1997, 2010 Contents v Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Display program references: DSPPGMREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-51 Print command usage: PRTCMDUSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-523.4. Overview of ILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-53 Overview of ILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-54 Integrated language environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-55 Creating ILE objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-56 Bind by copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-57 CALL and CALLPRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-58 Service program: Bind by Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-59 Create CL Module (CRTCLMOD) (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-60 Create CL Module (CRTCLMOD) (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-61 Create Program (CRTPGM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-63 Create Service Program (CRTSRVPGM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-65 Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-66 Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-67 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-68 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-69Unit 4. Intermediate CL programming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-1 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24.1. Additional control language programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-3 Additional control language programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-4 Job switches and %SWITCH built-in function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-5 Extracting part of a *CHAR value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-6 Example: Creating class profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-7 %SUBSTRING example: Saving libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-8 Declare CL variable revisited . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-9 Defined variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-11 Pointer, defined and based variables examples . . . . . . . . . . . . . . . . . . . . . . . . . . .4-12 Local data area, *LDA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-13 Accessing local data area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-14 Data area objects (*DTAARA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-15 Data area programming example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-16 Retrieving external attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-17 Example: Using RTVJOBA to make a general initial program . . . . . . . . . . . . . . . .4-18 RTVJOBA and CHGJOB example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-19 Convert date command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-20 CVTDAT example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-22 Using the prompter within a CL procedure or program . . . . . . . . . . . . . . . . . . . . . .4-23 Example: ?SNDMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-24 ?SNDMSG TOMSGQ(QSYSOPR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-25 Parameter prefix summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-26vi CL Programming for IBM i ©Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4.0.1 Student NotebookTOC Example: ?SNDMSG ?-TOUSR(*SYSOPR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-27 Example: SAVLIB ??LIB(APLIB) ?*DEV(TAP01) EBDOPT(*UNLOAD) (1 of 2) . . 4-28 Example: ?SAVLIB ??LIB(APLIB) ?*DEV(TAP01) ENDOPT(*UNLOAD) (2 of 2) 4-29 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-30 4.2. Defining messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-31 Defining messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-32 Messages are always sent to message queues: Type of message queues . . . . . 4-33 Message communication within a job: Sending . . . . . . . . . . . . . . . . . . . . . . . . . . 4-34 Job message queue *EXT (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-35 Job message queue *EXT (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-36 Which message types can be sent to which types of queues . . . . . . . . . . . . . . . . 4-37 Immediate and predefined message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-39 Predefined messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-40 Work with Message Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-41 Option 12: Work with message descriptions (WRKMSGD) . . . . . . . . . . . . . . . . . . 4-42 F6=Add (ADDMSGD) (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-43 F6=Add (ADDMSGD) (2 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-45 F6=Add (ADDMSGD) (3 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-50 F6=Add (ADDMSGD) (4 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-52 Using a predefined message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-54 Using an immediate message: SNDUSRMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-55 Predefined versus immediate messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-56 Duplicate message ID method (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-57 Duplicate message ID method (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-58 Merge Message File (MRGMSGF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-59 Override Message File (OVRMSGF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-60 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-62 4.3. Working with messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-63 Working with messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-64 Managing exceptions: User versus program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-65 Monitorable error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-67 MONMSG example: File availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-68 MONMSG example: F3 or F12 during prompting . . . . . . . . . . . . . . . . . . . . . . . . . 4-69 Monitor message command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-70 MONMSG: Program level and command level . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-74 Monitor message examples: Check object existence and authorization . . . . . . . . 4-76 Monitor message example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-77 MONMSG versus RCVMSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-78 Abnormally ending called program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-79 Using an *ESCAPE message to end a program . . . . . . . . . . . . . . . . . . . . . . . . . . 4-80 Sending an *ESCAPE message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-82 Standard way to display error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-83 Message subfile for error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-84 Message subfile DDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-85 Message subfile programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-86 Automatic replies to inquiry messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-88 Where an inquiry message gets its reply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-89 System reply list method: System-wide table of replies . . . . . . . . . . . . . . . . . . . . 4-90 ©Copyright IBM Corp. 1997, 2010 Contents vii Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook System reply list method automatic C reply to CPA7025 . . . . . . . . . . . . . . . . . . . 4-92 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-934.4. User-written tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-95 User-written tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-96 File overrides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-97 Overriding name and attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-98 File override scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-99 Override termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-100 Using a database file for user-written utility programs . . . . . . . . . . . . . . . . . . . . .4-101 Declaring the database file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-102 Database file operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-013 Use an output file from a display command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-104 Commands without an OUTFILE parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-016 Using QWCRSSTS API for system status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-108 Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-109 Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-110 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-111 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4-112Unit 5. Batch jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-1 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-25.1. Batch jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-3 Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-4 Batch jobs run asynchronously from interactive jobs . . . . . . . . . . . . . . . . . . . . . . . .5-6 SBMJOB starts an asynchronous job: Use *LDA to pass information . . . . . . . . . . .5-7 Submit job overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-8 Parameters for SBMJOB and their defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-9 Submit job example (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-10 Submit job example (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-11 Using a data queue to communicate with an asynchronous job that has already started  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-12 Data queue facts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-13 Create Data Queue (CRTDTAQ) command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-14 Send data queue (QSNDDTAQ) API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-19 Receive data queue (QRCVDTAQ) API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-22 Data queue example: Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-27 Data queue example: Receiving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-28 Using a file to communicate with an asynchronous job that has already started . .5-29 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-30 Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-31 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-32 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5-33Unit 6. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-1 Unit objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-26.1. Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-3 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-4 Simple command OR (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6-5viii CL Programming for IBM i ©Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4.0.1 Student NotebookTOC Simple command OR (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6 User-defined commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7 User command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8 Creating and running a command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9 Create Command (CRTCMD) (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10 Create Command (CRTCMD) (2 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11 Create Command (CRTCMD) (3 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13 Command execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15 Command execution: No validity checker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-16 User command example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17 Command source definition statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19 PARM statement (1 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20 PARM statement (2 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22 PARM statement (3 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23 PARM statement (4 of 4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24 How command processing programs receive parameters: RPG . . . . . . . . . . . . . 6-25 How command processing programs receive parameters: COBOL and CL . . . . . 6-26 Qualified name parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27 Qualified name parameter example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-28 Changing existing commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30 Changing IBM commands: New release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31 Restrict parameters of an IBM command: Example . . . . . . . . . . . . . . . . . . . . . . . 6-33 Proxy commands: CRTPRXCMD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34 Checkpoint (1 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35 Checkpoint (2 of 2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36 Workstation exercises . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37 Unit summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38 Appendix A. Prerequisite and checkpoint solutions . . . . . . . . . . . . . . . . . . . . . . . . . A-1 ©Copyright IBM Corp. 1997, 2010 Contents ix Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebookx CL Programming for IBM i ©Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookTMK Trademarks The reader should recognize that the following terms, which appear in the content of this training document, are official trademarks of IBM or other companies: IBM® is a registered trademark of International Business Machines Corporation. The following are trademarks of International Business Machines Corporation in the United States, or other countries, or both: AIX® AS/400® C/400® DB2® i5/OS® Integrated Language Environment® iSeries® Language Environment® Notes® OS/400® Power Systems™ Power Systems Software™ Rational® Redbooks® RPG/400® System i® WebSphere® Adobe is either a registered trademark or a trademark of Adobe Systems Incorporated in the United States, and/or other countries. Intel and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Windows is a trademark of Microsoft Corporation in the United States, other countries, or both. Other product and service names might be trademarks of IBM or other companies. © Copyright IBM Corp. 1997, 2010 Trademarks xi Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebookxii CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student Notebookpref Course description Control Language Programming for IBM i Duration: 4 days Purpose This classroom course is designed to teach the students to write control language (CL) programs which may be used to perform a variety of system and application control functions. The students are taught to write basic and intermediate level, interactive, and batch CL programs, user commands, and CL programs that function as user tools (programs that use the output of display commands as input). Audience This course is intended for application programmers, system programmers, and others who have a need to write control language programs. Prerequisites Before taking this course, the student should be able to: • Write simple programs in another programming language • Perform basic IBM i operations • Code the commands necessary to send inquiry and information messages • Use data description specifications (DDS) and the Rational Development Studio (formerly known as Websphere Development Studio, WDS) tools (Programming Development Manager (PDM) and source entry utility (SEU)) to create physical, logical, and display files • Use the WDS tools to enter CL source statements and create CL programs • Describe basic work management • Create a library, output queue, and a job description © Copyright IBM Corp. 1997, 2010 Course description xiii Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook These prerequisites can be met through successful completion of the following courses: • Introduction to IBM i for New Users (OV98) • IBM i Application Programming Facilities Workshop (OL49 or OV49)Objectives After completing this course, you should be able to: • Create CL programs that incorporate the full range of language operations and functions: Arithmetic, string, and boolean expressions Relational operations Built-in functions File handling Message handling Retrieving IBM i information Program interaction and parameter passing • Use the interactive source debugging facilities of STRDBG • Describe how to create and call Integrated Language Environment (ILE) modules, programs, and service programs • Create user-defined commands with and without parameters • Create a control language program that processes a database file • Create and invoke a program that is activated periodically and executes asynchronously from other jobs • State the purpose of the parameters on the CRTBNDCL command and each section of the control language compiler listingCurriculum relationship This course follows: Introduction to IBM i for New Users (OV98) IBM i Application Programming Facilities Workshop (OL49 or OV49)xiv CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student Notebookpref Agenda Day 1 Unit 1 - Class administration Unit 2 - Basic CL programming (topic 1) Lab 1 Lunch Unit 2 - Basic CL programming (topics 2 and 3) Labs 2 through 6 Day 2 Unit 3 - Program creation and debugging (topic 1) Unit 3 - Program creation and debugging (topics 2 and 3) Lab 7 Lunch Unit 4 - Intermediate CL programming (topic 1) Labs 8 and 9 Day 3 Unit 4 - Intermediate CL programming (topic 2) Labs 10 and 11 Lunch Unit 4 - Intermediate CL programming (topic 3) Labs 12 through14 Unit 4 - Intermediate CL programming (topic 4) Lab 15 Day 4 Unit 5 - Batch jobs Labs 16 and 17 Unit 6 - Commands (topic 1) Lunch Lab 18 parts A, B, and C © Copyright IBM Corp. 1997, 2010 Agenda xv Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebookxvi CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 1. Class administration What this unit is about Administrative matters, such as facility layout, are discussed. The students introduce themselves and the course objectives and agenda are presented. What you should be able to do After completing this unit, you should be able to: • List the units to be presented in the course • State the course prerequisites and objectives • Evaluate how well the course matches your needs based on the course objectives • Find and use the teaching locations facilities © Copyright IBM Corp. 1997, 2010 Unit 1. Class administration 1-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Control Language Programming for IBM i Powertm with IBM i © Copyright IBM Corporation 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM. 5.4Figure 1-1. CL programming for IBM i OL209.0Notes:1-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit objectives IBM i After completing this unit, you should be able to: • List the units to be presented in the course • State the course prerequisites and objectives • Evaluate how well the course matches your needs based on the course objectives • Find and use the teaching locations facilities © Copyright IBM Corporation 2010 Figure 1-2. Unit objectives OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 1. Class administration 1-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Administration IBM i Messages Restrooms Smoking areas Phones Breaks Class hours Eating establishments © Copyright IBM Corporation 2010Figure 1-3. Administration OL209.0Notes:1-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Course objectives IBM i • Create CL programs that incorporate the full range of language operations and functions: – Arithmetic, string, and boolean expressions – Relational operations – Built-in functions – File handling – Message handling – Retrieving system information – Program interaction and parameter passing • Use the interactive source debugging facilities of STRDBG • Describe how to create and call Integrated Language Environment (ILE) modules, programs, and service programs • Create user-defined commands with and without parameters • Create a control language program that processes a database file • Create and invoke a program that is activated periodically and executes asynchronously from other jobs • State the purpose of the parameters on the CRTBNDCL command and each section of the control language compiler listing © Copyright IBM Corporation 2010 Figure 1-4. Course objectives OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 1. Class administration 1-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisites IBM i Before taking this course, the student should be able to: • Write simple programs in another programming language • Perform basic IBM i operations • Code the commands necessary to send inquiry and information messages • Use data description specifications (DDS) and the Rational Development Studio (WDS) tools, (Programming Development Manager (PDM) and source entry utility (SEU)) to create physical, logical, and display files • Use the WDS tools to enter CL source statements and create CL programs • Describe basic work management • Create a library, output queue, and a job description © Copyright IBM Corporation 2010Figure 1-5. Prerequisites OL209.0Notes:1-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Agenda (1 of 2) IBM i Day 1 • Unit 1: Class administration • Unit 2: Basic CL programming (topic 1) – Lab 1 • Unit 2: Basic CL programming (topics 2 and 3) – Labs 2 through 6 Day 2 • Unit 3: Program creation and debugging – Lab 7 • Unit 4: Intermediate CL programming (topic 1) – Labs 8 and 9 © Copyright IBM Corporation 2010 Figure 1-6. Agenda (1 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 1. Class administration 1-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Agenda (2 of 2) IBM i Day 3 • Unit 4: Intermediate CL programming (topic 2) – Labs 10 and 11 • Unit 4: Intermediate CL programming (topic 3) – Labs 12 through 14 • Unit 4: Intermediate CL programming (topic 4) – Lab 15 Day 4 • Unit 5: Batch jobs – Labs 16 and 17 • Unit 6: Commands – Lab 18 parts A, B, and C © Copyright IBM Corporation 2010Figure 1-7. Agenda (2 of 2) OL209.0Notes:1-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Introductions IBM i • Your name and city • Company and organization name • Type of business • Previous experience • Expectations Trainee © Copyright IBM Corporation 2010 Figure 1-8. Introductions OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 1. Class administration 1-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit summary IBM i Having completed this unit, you should be able to: • List the units to be presented in the course • State the course prerequisites and objectives • Evaluate how well the course matches your needs based on the course objectives • Find and use the teaching locations facilities © Copyright IBM Corporation 2010Figure 1-9. Unit summary OL209.0Notes:1-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 2. Basic CL programming What this unit is about The class begins with a review of IBM i concepts that are related to CL programming. The syntax of CL programming and the techniques for writing basic CL programs follows. What you should be able to do After completing this unit, you should be able to: • Understand the concepts of object, library and library list • Describe how the commands are used in CL programs • Describe the application development tools • Write basic CL programs How you will check your progress • Review questions • Machine exercises References IBM i Information Center - CL Programming © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit objectives IBM i After completing this unit, you should be able to: • Understand the concepts of object, library and library list • Describe how the commands are used in CL programs • Describe the application development tools • Write basic CL programs © Copyright IBM Corporation 2010Figure 2-1. Unit objectives OL209.0Notes:2-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 2.1. CL programming concepts © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL programming concepts IBM i After completing this topic, you should be able to: • Describe the concepts of object, library and library list • Enter, create and execute a basic CL program, given the source statements for the program © Copyright IBM Corporation 2010Figure 2-2. CL programming concepts OL209.0Notes:2-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Review of IBM i CL programming concepts IBM i Prerequisite review questions in Student Notebook Answer questions now Class discussion of answers Work together © Copyright IBM Corporation 2010 Figure 2-3. Review of IBM i CL programming concepts OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (1 of 11) IBM i 1. What is an IBM i library? a. A physical disk storage area for objects b. The only structure on the i that is not an object c. A group of files d. A directory of objects © Copyright IBM Corporation 2010Figure 2-4. Prerequisite review (1 of 11) OL209.0Notes:2-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Object identification IBM i All objects are uniquely identified by library, name, and type. DSPOBJD OBJ(QGPL/QBATCH) OBJTYPE(*ALL) OUTPUT(*PRINT) LIBRARY NAME TYPE Display Object Description - Basic Library: QGPL Object Type Freed Size Text QBATCH *JOBQ NO 16896 Batch Subsystem Queue QBATCH *JOBD NO 1536 Batch Subsystem Job Description QBATCH *CLS NO 512 Batch Subsystem Class © Copyright IBM Corporation 2010 Figure 2-5. Object identification OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (2 of 11) IBM i 2. For most object types, if no library is specified when the object is created, in which library is it placed? a. Current library b. Temporary library: QTEMP c. System library: QSYS d. General purpose library: QGPL © Copyright IBM Corporation 2010Figure 2-6. Prerequisite review (2 of 11) OL209.0Notes:2-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty In which library is an object created? IBM i • Unqualified name on its create command: (*CURLIB/object-name) Does No Job Have a Yes Current QGPL Current Library Library? • Qualified name on its create command: (library-name/object-name) – Placed in specified library • Exception: – Some object types, such as libraries and user profiles, are always in library QSYS. © Copyright IBM Corporation 2010 Figure 2-7. In which library is an object created? OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (3 of 11) IBM i 3. When is a jobs library list used to find an object? a. Always b. Only if the library list has been replaced since sign-on c. Only if system value QUSRLIBL has value *LIBL d. Only if the object name is unqualified © Copyright IBM Corporation 2010Figure 2-8. Prerequisite review (3 of 11) OL209.0Notes:2-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Finding an object IBM i Unqualified: CALL PAY02 /* USE LIBRARY LIST */ Qualified: CALL PAYLIB/PAY02 /* USE PAYLIB */ QSYS INQLIB Jobs Library List QCVVVQCXXX PAY77 AP60 QSYS QHLPSYS QCZZZ QCYYY PAY99 AP55 QUSRSYS QPDA QRPG PAYTSTLIB PAYLIB PAYTSTLIB AP55 PAY02 PAY01 PAY04 QGPL QTEMP PAY01 PAY05 PAY02 PAY05 PAYLIB © Copyright IBM Corporation 2010 Figure 2-9. Finding an object OL209.0 Notes: When using an object, specify either a qualified or an unqualified name. If a qualified name is used, then the system looks for the object only in the library specified by the qualified name. If an unqualified name is used, the system looks in the first library in the jobs library list. If not found, then it looks in the second library in the jobs library list, and so on. Objects with the same name and type may exist in libraries later in the jobs library list. They are not used. This feature allows you to set up a testing or training environment. Create duplicate objects in a test library and place the test library, before the production library in the jobs library list. In this visual, two libraries have a program named PAY02. The library list can be used to select one of them at execution time. This concept is useful in setting up a testing or training environment. The library list is established when the job starts from the job description, user profile, sign-on screen, and system values. It may be changed during the job. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (4 of 11) IBM i 4. What command could you use to see your jobs library list? a. DSPLIBL b. DSPJOB c. EDTLIBL d. All of the above 5. What command can you use to alter your jobs library list? a. EDTLIBL b. ADDLIBLE c. CHGLIBL d. All of the above 6. Suppose you add library PAYLIB to your library list, then sign off. You sign on again. a. PAYLIB is not in your library list. b. PAYLIB is in your library list. c. PAYLIB is in your library list if you use the same password you did earlier. d. PAYLIB is in your library list if you use the same workstation as you did earlier. © Copyright IBM Corporation 2010Figure 2-10. Prerequisite review (4 of 11) OL209.0Notes:Do not confuse DSPLIB with DSPLIBL. DSPLIB shows the objects within a library.2-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Library list IBM i System libraries QSYS (15 maximum) QHLPSYS QUSRSYS QPDA Product libraries QRPG * LIBL Current library PAYLIB (*CURLIB) QGPL *USRLIBL User libraries (250 maximum) QTEMP PAYTSTLIB © Copyright IBM Corporation 2010 Figure 2-11. Library list OL209.0 Notes: This figure shows the complete library list for a job. The library list is composed of several sections: • The system libraries • The product libraries (automatically managed by the system) • The current library • The user libraries The abbreviations *LIBL and *USRLIBL, and the library lists sections that they refer to, are used frequently on i commands. The parts of the library list with which you normally work include the current library and the user libraries. *SYSLIBL refers to the system portion of a jobs library list. It is initially set by system value QSYSLIBL and may be changed by the command CHGSYSLIBL. The user part of the jobs library list is initially set through system value QUSRLIBL. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookThe following commands can be used to change the user library part of the library list:ADDLIBLE, RMVLIBLE, CHGLIBL, and EDTLIBL.The job description for a job can override the system value QUSRLIBL for the user portionof the library list. The current library may be changed through the commands CHGCURLIBand CHGLIBL. When a batch job is submitted, the SBMJOB command may specify acurrent library and library list that is different than the one for the submitting job.Current library can be specified on the sign-on screen, in the users profile, and in the jobdescription.Libraries help organize objects. You are not required to set up libraries on the system. Ifyou take defaults for everything that you do, then all of the objects that you create, with afew exceptions, are placed in library QGPL. By default, QGPL is one of the libraries in thesystem value QUSRLIBL.Libraries give you the opportunity to organize objects by security and backup requirements,by application, by user, by object type, or by use. Libraries make managing the objects onthe system easier.Only libraries with public authority no greater than *USE can be added to the systemportion of the library list. This is enforced only during the addition to the list. It is notenforced after the library is already on the list. It affects the commands CHGSYSLIBL,CRTSBSD, CHGSBSD, and system value QSYSLIBL.The system part comes from system value QSYSLIBL. The product libraries, if present,come from a command that is currently being run. The current library comes from theprofile or sign-on screen. The user part comes from the job description or system valueQUSRLIBL.2-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Prerequisite review (5 of 11) IBM i 7. On a command line, keying a question mark (?) and pressing Enter, or using Function Key 4: a. Shows you a menu from which you can search for a command. b. Causes an error. c. Shows you the general help text. d. Shows you the valid function keys. © Copyright IBM Corporation 2010 Figure 2-12. Prerequisite review (5 of 11) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook ?DSPOBJD OR DSPOBJD F4 IBM i Display Object Description (DSPOBJD) Type choices, press Enter. Object . . . . . . . . . . _______ Name, generic*, *ALL Library . . . . . . . . *LIBL Name, *LIBL, *USRLIBL... Object Type . . . . . . . _______ *ALL, *ALRTBL, *AUTL... + for more values _______ Detail . . . . . . . . . . *BASIC *BASIC, *FULL, *SERVICE ASP device: Device . . . . . . . . . * Name, *, *ALLAVL... Search type . . . . . . *ASP, *ASPGRP Output . . . . . . . . . . * *, *PRINT, *OUTFILE Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 2-13. ?DSPOBJD OR DSPOBJD F4 OL209.0Notes:This figure shows the prompt display for the Display Object Description command(DSPOBJD). You may invoke it by typing the command name followed by F4 or by typing aquestion mark followed by the command name and pressing the Enter key. The choicesyou have for the parameters are shown on the right side of the display.Unless the user profile has attribute USROPT(*CLKWD), parameter choices rather thankeywords are shown. F11 flip-flops between showing parameter choices and parameterkeywords.By default, when a command is prompted, prompting is in the choices format.2-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Choices = F11 => keywords IBM i Display Object Description (DSPOBJD) Type choices, press Enter. Object . . . . . . . . . . . . . OBJ _______ Library . . . . . . . . . . . . *LIBL Object Type . . . . . . . . . . OBJTYPE _______ + for more values _______ Detail . . . . . . . . . . . . . DETAIL *BASIC ASP device ASPDEV Device . . . . . . . . . . . . * _______ Search type. . . . . . . . . . _____ Output . . . . . . . . . . . . . OUTPUT *_______ Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 2-14. Choices = F11 => keywords OL209.0 Notes: F11 has been pressed and the keywords are shown. This alternative shows the keywords rather than the choices. Notice that in the two previous visuals, some parameters have default values. On a prompt display that is showing choices, you may see three dots indicating additional choices. You can find the additional choices by typing a question mark (?) for the parameter value and pressing the Enter key. The system then shows the complete list of choices that may be entered for that parameter. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (6 of 11) IBM i 8. When an error message is displayed, you may move the cursor to it and press the Help key to: a. Take a default reply to the message. b. Remove the message. c. Send a copy of the message to the system operator. d. See additional information about the error. © Copyright IBM Corporation 2010Figure 2-15. Prerequisite review (6 of 11) OL209.0Notes:2-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Help key: Additional information IBM i Selection or command -->SDPMSG __Command SDPMSG. in library *LIBL not found. Additional Message Information Message ID . . : CPD0030 Severity ... : 30 Message type . : INFO Date sent . . : 09/22/89 Time sent . . : 19:32:33 From program . : QOUCMD HELP Instruction . : 0000 To program . . : QOUCPP Instruction . : 0000 Message . . . : Command SDPMSG, in library *LIBL not found. Cause . . . . : If a library was not specified, the command was not found in the libraries in the library list. If library was specified, the command was not found there. Recovery . . . : Change the command name or correct the library name, and then try the command again. Press enter to continue F3=Exit F10=Display message in job log F12=Cancel © Copyright IBM Corporation 2010 Figure 2-16. Help key: Additional information OL209.0 Notes: Positioning the cursor on the same line as the message and then pressing the Help key displays the second-level message text. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (7 of 11) IBM i 9. In SEU or in LPEX Editor, what line command allows you to key a new line? a. A (Add Line) b. I (Insert Line) c. M (More Lines) d. B (Blank Line) 10. Which function can SEU or LPEX Editor not perform? a. Check field names for correct spelling b. Syntax check source statements c. Globally change the spelling of a word d. Copy part of another source member to the one being edited © Copyright IBM Corporation 2010Figure 2-17. Prerequisite review (7 of 11) OL209.0Notes:2-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Prerequisite review (8 of 11) IBM i 11. While editing a source member with source entry utility (SEU), you remember a function of SEU, but cannot remember how to use it. You could: a. Move the cursor to the part of the SEU display in question and press the Help key. b. Examine the function key descriptions on the bottom of the display and try any that seem likely to help. c. Read the SEU Reference Manual. d. All of the above 12. Which of the following statements is true? a. Source programs are IBM i objects. b. A source file can contain only one source member. c. Source programs are members of source files, which in turn are objects in a library. d. Source programs are members of libraries. © Copyright IBM Corporation 2010 Figure 2-18. Prerequisite review (8 of 11) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-21 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Creating and calling a CL program IBM i 1. Create a source physical file CRTSRCPF FILE(QCLSRC) QCLSRC 2. Add member; edit source STRSEU SRCFILE(QCLSRC) SRCMBR(AB) TYPE(CLLE) Object Type - or - *FILE STRPDM; Work with members; PGM F6 = Create Member CALL PGM(A) AB 3. Create program CALL PGM(B) CRTCLPGM PGM(AB) ENDPGM SRCFILE(QCLSRC) SRCMBR(*PGM) - or - More source STRPDM; Work With Members; members may be Option 14 = Compile added. 4. Call the program AB CALL PGM(*LIBL/AB) - or - Object Type STRPDM; Option C = Call *PGM © Copyright IBM Corporation 2010Figure 2-19. Creating and calling a CL program OL209.0Notes:2-22 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Prerequisite review (9 of 11) IBM i Use the data description specifications below to answer the next two questions: A REF(FIELDREF) A CA03(03 Exit) A R PAYFMT1 A 5 30 Payroll A 8 11 Employee Number A EMPNO R I 8 30 A 9 11 Hours A HOURS R I 9 16 13. The above specifications are for what type of object? a. Printer file b. Display file c. Physical file d. Logical file 14. Which of the following statements is true? a. F3=Exit appears automatically on the display screen. b. The specifications are incorrect because EMPNO and HOURS have undefined field lengths. c. These statements must be compiled before they can be used. d. Function key 3 automatically ends the program. © Copyright IBM Corporation 2010 Figure 2-20. Prerequisite review (9 of 11) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-23 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review (10 of 11) IBM i 15. The i definition of a batch job is: a. A job that requires no user interaction. b. A job that processes a batch of transactions. c. Both (a) and (b) d. A job that originates from a job queue. 16. The i definition of an interactive job is: a. From the start to the finish of a program run at a workstation. b. All work done at a workstation from sign-on to sign-off. c. All programs within a procedure. d. A program that interacts with the user. 17. What do the device description for a workstation, its interactive job, and its workstation message queue have in common? a. Their name b. Their authorization list c. Their owner d. Their library © Copyright IBM Corporation 2010Figure 2-21. Prerequisite review (10 of 11) OL209.0Notes:2-24 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Prerequisite review (11 of 11) IBM i 18. The stages of a batch job are: a. Job queue to active to output queue. b. Input queue to program to printer. c. Reader queue to storage pool to spooled file. d. Job description to routing entry to printer. 19. The display job command, DSPJOB, shows your jobs: a. Library list. b. Job log. c. Default output queue. d. All of the above. 20. The WRKSPLF command: a. Creates a spool file. b. Shows you all of your spooled output. c. Starts printing your spooled files. d. Works with system, printer, or logical files. © Copyright IBM Corporation 2010 Figure 2-22. Prerequisite review (11 of 11) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-25 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Batch and interactive jobs IBM i User Workstation *MSGQ DSPMSG *MSGQ WRKJOB DOUG WRKMSG DSP43 Interactive Job *DEVD DSP43 No. User Job SIGN ON: Job Start: 123456/DOUG/DSP43 Call... User and Workstation *USRPRF DOUG SBMJOB... SIGNOFF: Job End { *MSGQS allocated Batch Job 123457/DOUG/QDFTJOBD WRKSBMJOB *JOBQ *OUTQ *OUTQ Process WRKSPLF © Copyright IBM Corporation 2010Figure 2-23. Batch and interactive jobs OL209.0Notes:The user message queue is created when the user profile is created. The workstationmessage queue is created when the workstation device description is created.The job identification consists of three pieces of information: a sequential number, theusers name, and for an interactive job, the workstation name, and for a batch job, the jobdescription name.When a user signs on to the system, that users message queue and that workstationsmessage queue are allocated automatically to the users job and set to notify deliverymode. Any old messages in either of these queues are reset to new messages. When theuser signs off, both message queues are deallocated and revert to hold delivery mode.If more than one user is on the system with the same profile, the user message queue isallocated only to the first user who signs on with that profile.2-26 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Workstation exercises IBM i • Lab 1: Set up programming environment (required) © Copyright IBM Corporation 2010 Figure 2-24. Workstation exercises OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-27 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook2-28 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 2.2. Basic CL programming © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-29 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Basic CL programming IBM i After completing this topic, you should be able to: • Describe the structure and coding rules of CL programs • Write CL programs that use – Display files – Conditional execution logic – Passing of data between programs – Expressions – Change variable command – Concatenation © Copyright IBM Corporation 2010Figure 2-25. Basic CL programming OL209.0Notes:In this topic, we discuss some of the basic rules for coding a CL program.We consider the components that go to make a program (in any language). We explore thedifferent CL statements for building a well-structured CL program.2-30 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Reference manuals IBM i © Copyright IBM Corporation 2010 Figure 2-26. Reference manuals OL209.0 Notes: The CL Programming manual, (available in PDF format in the IBM i Information Center) has a chapter for each aspect of CL programming. For instance, there is a chapter on defining messages. All other reference information, including CL commands, can be found in the i Information Center, including their syntax diagrams and a brief description. For a detailed description of each parameter, you can use the online help text on the i system. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-31 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Control language IBM i CL commands: Consistent interface Prompting and Help CONTROL LANGUAGE CL programs: Better performance Manage exceptions Control sequence of application programs Front end to application programs - Overrides - Library list Users - Allocate objects - Open files Operators Programmer/Operator tools Programmers Frequently used commands Utility functions © Copyright IBM Corporation 2010Figure 2-27. Control language OL209.0Notes:On some computer systems, programmers write high-level language programs to do partof the application and surround it with instructions to the supervisor language to executethe program. Operator functions often require instructions to the supervisor program in adifferent format.On the i, control language programs span both of these areas. A function that previouslyrequired a user to type a series of instructions one at a time from a run book, can now beput into a CL program and run in one step. A control language program can solve some ofthe application requirements that are normally written in Report Program Generator (RPG),COBOL, or another high-level language.All system functions are run using control language. Control language may be enteredinteractively at a workstation. Several statements may be typed together in a diskette or ina source file source member, then submitted to a job queue as a job stream They may beentered into the system as the source for a program. That program can be compiled andrun like any other high-level language program. Control language can be run in aninteractive or batch environment.2-32 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Control language can be compiled. The advantages of compiling control language are that it runs faster and can include logic. Control language programs perform these functions: • Simplify operations. • Control the execution sequence of programs in an application. • Interpret errors and exceptions that occur during program execution and bypass or correct that error. • Set up an environment that is customized for a particular job by changing library lists, default output queue, job date, and so forth. • Control the running of application programs. • Perform front-end tasks for application programs. • Process the output of a DSPxxx command as input, in order to perform a utility function (user tool). The main purpose of control language programs is to control the running of the high-level language programs of your application. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-33 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL commands IBM i Verb Item Item Verb Abbreviation Abbreviation Abbreviation F File Create Physical file CRT PF Logical file LF Display file Delete DSPF Program PGM Control language program DLT RPG program CLPGM COBOL program RPGPGM CBLPGM Library Change LIB Display Work With . . CHG . . DSP . . WRK © Copyright IBM Corporation 2010Figure 2-28. CL commands OL209.0Notes:This figure shows the structure of control language commands. A control languagecommand consists of a command followed by its parameters. A command itself consists ofan action (like a verb) and an item abbreviation.Although there are thousands of English verbs, there are only a few actions you canperform on programs, files, and other objects. When these actions are grouped into similarfunctions, that number is reduced even further.For example, display includes all forms of viewing on the computer. Abbreviate display bydropping the vowels and reducing the number of consonants to three: DSP.Similarly, create includes compiling and building. Drop the vowels and reduce theconsonants to three: CRT.To remove, erase, or delete something on a computer system, use delete. Abbreviate thesame way as before: DLT.2-34 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Commands act on objects such as files, programs, and output queues. Use the same abbreviation scheme: PGM (program), F (file), PF (physical file), LF (logical file), and OUTQ (output queue). Notice the exceptions to the abbreviation rule. By combining the action abbreviations with the object abbreviations, all of the control language commands are formed. There are a large number of commands, but think of them as a few dozen abbreviated actions and a few dozen abbreviated objects or object phrases. If you can remember the abbreviations, the combinations which produce all of the CL commands are easily learned. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-35 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL command syntax (1 of 4) IBM i [?] [label-name:] [library-name/] command-name [parameter-set] []... Optional ?... Prompt, like F4, for commands within programs Precedes label or command label-name. . . Identifies statement for branching, breakpoints and traces library-name. . . Usually omitted since IBM commands are in QSYS keyword value LABEL1: DSPLIB LIB(PAYLIB) OUTPUT(*PRINT) delimiter for label no space blank blank © Copyright IBM Corporation 2010Figure 2-29. CL command syntax (1 of 4) OL209.0Notes:Labels are only used when the command is in a CL program.2-36 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty CL command syntax (2 of 4) IBM i • Keyword format – DSPLIB LIB(PAYLIB) OUTPUT(*PRINT) – DSPLIB OUTPUT(*PRINT) LIB(PAYLIB) • Positional format – DSPLIB PAYLIB *PRINT • Combination format – DSPLIB PAYLIB OUTPUT(*PRINT) © Copyright IBM Corporation 2010 Figure 2-30. CL command syntax (2 of 4) OL209.0 Notes: When F4 is used to prompt for a command, it is entered in keyword format. This figure shows both the keyword form and the positional form for entering CL commands. The keywords may be omitted if the parameter values are entered in the sequence in which they are listed in the Information Center. All three commands on this figure perform exactly the same function. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-37 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL command syntax (3 of 4) IBM i continuation within a program quoted character string variables start two apostrophes with & SNDUSRMSG MSG(Today s balance is *CAT &BAL) + MSGTYPE(*INFO) /* Show balance */ predefined values comment start with * © Copyright IBM Corporation 2010Figure 2-31. CL command syntax (3 of 4) OL209.0Notes:If the parameter for a text field is not correctly defined in the prompt override program andthe text string retrieved by the prompt override program contains a quote, the commanddoes not prompt correctly.Make sure that you double any embedded apostrophes, for example: • (‘Carole”s Library’)When you want to write comments in your CL procedures or add comments to commandsin your procedures, use the character pairs /* and */. The comment is written betweenthese symbols.2-38 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty CL command syntax (4 of 4) IBM i /* This is a full-line comment */ SNDRCVF DEV(*FILE) RCDFMT(MENUFMT) SNDRCVF RCDFMT(MENUFMT) SNDRCVF *N MENUFMT Take default for positional parameter. generic name DSPOBJD OBJ(PAYLIB/PAY*) OBJTYPE(*PGM *FILE) Connects parts Blank to separate of a qualified list elements name © Copyright IBM Corporation 2010 Figure 2-32. CL command syntax (4 of 4) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-39 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Coding rules (1 of 2) IBM i • Variable name – Stores and updates data and receives parameters. It must begin with an & character. • Colon – Separates label from command • Blanks – Separates command parameters • Parentheses – Separates keywords and values • Slash – Connects parts of qualified names • Apostrophes – At the beginning and at the end of a quoted character string © Copyright IBM Corporation 2010Figure 2-33. Coding rules (1 of 2) OL209.0Notes:2-40 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Coding rules (2 of 2) IBM i • /* and */ – Used to frame a comment • Predefined values – Start with * such as *ALL • Generic names – End with * such as PAY* • Plus (+) or minus (-) – Used at the end of a line that continues on a next line • *N – Indicates the absence of a positional parameter © Copyright IBM Corporation 2010 Figure 2-34. Coding rules (2 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-41 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL program structure IBM i Description Program Statement Start of program PGM (Optional) COPYRIGHT (Optional) Declare file and variables DCLF (maximum of five) DCL DCL Program-Level MONMSG Monitor messages MONMSG IF IBM Commands ELSE COMMAND Command-Level MONMSG Monitor Messages MONMSG and/or User commands End of program ENDPGM (optional) © Copyright IBM Corporation 2010Figure 2-35. CL program structure OL209.0Notes:The following statements are examples of the basic CL program structure: PGM: Optional. Required if the program is to receive parameters when called. DCL: Declare a variable. DCLF: Declare a file and its variables. (As of V5R3, it is possible to declare up to five different files.) ENDPGM: Optional. Assumed if not present.Most commands are allowed in CL programs.In the syntax diagrams in the CL Reference manual, there is a group of codes such as“JOB: B,I PGM: B,I”. If the code includes PGM, the command may be used in a CLprogram. The B (batch) and I (interactive) indicate in what type of job the program may berun.The COPYRIGHT command defines the text of a copyright string to be incorporated in thecompiled object. It is valid only within a CLLE source member. If used, the COPYRIGHT2-42 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty command must follow the PGM command and precede any other commands except for DCL and DCLF. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-43 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Declare CL variable IBM i DCL VAR(&NAME) TYPE( ) LEN( ) VALUE( ) VAR( ) TYPE( ) LEN( ) VALUE( ) &Name *DEC Default (15 5) Default (0) (1 to 15 digits) Max (15 9) &Name *INT or *UINT Default (4) Default (0) 2, 4 or 8 bytes Max (8) &Name *CHAR Default (32) Default (b) (1 to 32,767) Max Max value (32,767) 5000 chars &Name *LGL Default (1) Default (‘0’) &Name *PTR Unspecified Initialized to an address © Copyright IBM Corporation 2010Figure 2-36. Declare CL variable OL209.0Notes:Use the declare CL variable (DCL) command to declare any variables needed in theprogram that are NOT already implicitly declared. (Declaring a file with fields, implicitlydeclares the fields in the file as CL variables.) Logical variables may be either a character‘1’ (true) or ‘0’ (false). If a field is declared, but not referenced by any other command in theprogram, the variable is not included in the compiled program. While the maximum lengthof a character variable may be 32,767 characters long, the VALUE parameter can initializethe value of the variable to be no longer than 5,000 characters.A pointer (*PTR) variable is declared in order to contain the value of an address in memorythat points to data. The length of a pointer is never specified on the declare, but the lengthdefaults to a fixed length of 16 bytes. We’ll discuss pointer variables and their use in moredetail later in the course.2-44 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Declare CL variables examples IBM i • Examples: –(1) DCL &A *LGL VALUE ( 1 ) –(2) DCL VAR(&B) TYPE(*CHAR) LEN(5) VALUE(ABCD) –(3) DCL &C *DEC (6 2) 543.21 –(4) DCL &CHAR *CHAR LEN(10) DCL &PTR ADDRESS(&CHAR) – (5) DCL &QUALOBJ *CHAR LEN(20) DCL &OBJ *CHAR LEN(10) STG(*DEFINED) + DEFVAR(&QUALOBJ 1) DCL &LIB *CHAR LEN(10) STG(*DEFINED) + DEFVAR(&QUALOBJ11) © Copyright IBM Corporation 2010 Figure 2-37. Declare CL variables examples OL209.0 Notes: The examples in this visual show how to declare a logical, character, decimal, pointer, and a structured variable. In the first example, field &A is declared as a logical variable with initial value of character ‘1’ (true). In the second example, field &B is declared as a character variable, 5 positions long, with initial value ABCD. This statement is coded using the full keyword syntax. In the third example, variable &C is declared as a decimal variable, six positions long. For &C, the last two positions are to the right of the decimal point, and the initial value is 543.21. In the fourth example, variable &CHAR is declared as a character variable, ten positions long. The second DCL command declares a pointer variable which is initialized to point to the &CHAR variable in the programs automatic storage. In the fifth example, the first DCL command declares a 20-character variable in the programs automatic storage. The second DCL command declares a variable named &OBJ which refers to the first 10 characters of the &QUALOBJ variable. The last DCL command © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-45 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebookdeclares a variable named &LIB which can be used to reference the last 10 characters ofthe &QUALOBJ variable.2-46 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Declaring a display file in a CL program IBM i *FILE: QDDSSRC Member: INQDSP *FILE: INQDSP R INQFMT CA03(03 EXIT) Format: INQFMT 1 29 INQUIRY MENU CRTDSPF 4 29 1. Customer Inquiry Indicators: 03 5 29 2. Item Inquiry Fields: CHOICE 6 29 3. Vendor Inquiry tion 7 29 90. Sign off es crip 10 29 Type choices, press enter. Ed 11 29 Option: s *FIL CHOICE 2A I 11 us e 37 D CL 24 29 F3=Exit T BN CR *FILE: QCLSRC Member: INQPGM *PGM: INQPGM PGM CRTCLPGM Format: INQFMT DCLF FILE(INQDSP) Variables: &IN03 SNDRCVF RCDFMT(INQFMT) &CHOICE . . . ENDPGM © Copyright IBM Corporation 2010 Figure 2-38. Declaring a display file in a CL program OL209.0 Notes: Considerations: • There is a maximum of five DCLF statements per program. • The program does not set up storage for fields in unreferenced formats. • Fields in referenced formats are implicitly declared in the program. • Control language programs do not support zoned decimal numbers. Zoned decimal numbers from display files are converted automatically to packed decimal numbers. • These commands also reference files: SNDF, RCVF, SNDRCVF, ENDRCV, and WAIT. Command definitions and files referenced by a DCLF statement are referenced at program creation time. Therefore, they must exist when the program is created and when it is executed. Also, they must be in the qualifying library (if qualified) or in the jobs library list (if unqualified) at program creation time and at program run time. Other object types are not referenced at compile time and must exist and be able to be found either through the qualifying library (if qualified) or the jobs library list (if unqualified) only at run time. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-47 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using a display file in a CL program: Method one IBM i INQUIRY MENU 1. Customer Inquiry 2. Item Inquiry 3. Vendor Inquiry 90. Sign off PGM Option: DCLF FILE(INQDSP) Type choices, press enter. F3=Exit BEGIN: SNDRCVF RCDFMT(INQFMT) IF &IN03 RETURN ELSE IF (&CHOICE *EQ 1) CALL INQCUS ELSE IF (&CHOICE *EQ 2) CALL INQITM ELSE IF (&CHOICE *EQ 3) CALL INQSUP ELSE IF (&CHOICE *EQ 90) SIGNOFF GOTO BEGIN ENDPGM © Copyright IBM Corporation 2010Figure 2-39. Using a display file in a CL program: Method one OL209.0Notes:In this program, &CHOICE is a character variable. • A display file declared in a control language program is opened for input and output. • A declared file is opened at the first occurrence of an SNDF, RCVF, or SNDRCVF command.If the file name is qualified at compile time, the file must be in that library at run time. If youhave used the library list at compile time, the file must be in a library on the current librarylist at run time.2-48 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using a display file in a CL program: Method two IBM i INQUIRY MENU 1. Customer Inquiry you 2. Item Inquiry can also write: 3. Vendor Inquiry 90. Sign off PGM Option: DCLF FILE(INQDSP) Type choices, press enter. SNDRCVF RCDFMT(INQFMT) F3=Exit DOWHILE (&IN03 = 0) SELECT WHEN (&CHOICE *EQ 1) CALL INQCUS WHEN (&CHOICE *EQ 2) CALL INQITM WHEN (&CHOICE *EQ 3) CALL INQSUP WHEN (&CHOICE *EQ 90) SIGNOFF ENDSELECT SNDRCVF RCDFMT(INQFMT) ENDDO ENDPGM © Copyright IBM Corporation 2010 Figure 2-40. Using a display file in a CL program: Method two OL209.0 Notes: The SELECT statement is a neater way of constructing the flow, avoiding the use of the GOTO command. We review the SELECT group in a moment. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-49 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Display file operations IBM i Inquiry Menu INQDSP DCLF FILE(INQDSP) SNDF RCDFMT(INQFMT) RCVF RCDFMT(INQFMT) SNDRCVF RCDFMT(INQFMT) © Copyright IBM Corporation 2010Figure 2-41. Display file operations OL209.0Notes:It is not obvious that a format could be written once (SNDF) and read (RCVF) repeatedlywithout rewriting it. Each RCVF unlocks the keyboard and invites input. • The DCLF command declares the display file to the program. • The SNDF command sends the format from the program to a display file. • The RCVF receives the formats from the display file to the program. • The SNDRCVF writes a format to the display file, then receives the format back into the program.By default, RCVF and SNDRCVF wait for a reply. If WAIT(*NO) is specified, the programcontinues until a WAIT command is encountered.2-50 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty CHGVAR: Arithmetic calculations IBM i + CHGVAR VAR(CL-variable) VALUE(operand - operand) / * CHGVAR VAR(&AMT) VALUE(-37.2) CHGVAR VALUE(&COUNT + 1) VAR(&COUNT) CHGVAR &AMT ((&PRICE - &DISCOUNT) * &QTY) © Copyright IBM Corporation 2010 Figure 2-42. CHGVAR: Arithmetic calculations OL209.0 Notes: CHGVAR can be used for arithmetic calculations by putting the calculation in the VALUE parameter as an arithmetic expression. The CHGVAR command is the general command to perform simple assignments, arithmetic calculations, data type conversion, and character string manipulation. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-51 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CHGVAR: Conversion between *CHAR and *DEC data types IBM i CHGVAR VAR(&A) VALUE(&B) Character Variable &A Decimal Variable &B LEN Converted Result LEN Specified Value 7 0023.00 52 23.00 or +23 7 -003.90 52 -3.9 7 -123.67 52 -123.67 CHGVAR VAR(&B) VALUE(&A) Decimal Variable &B Character Variable &A LEN Converted Result LEN Specified Value 52 123.10 10 bb+123.1bb 50 123 10 bbb+123.00 52 -123.00 10 -123bbbbbb © Copyright IBM Corporation 2010Figure 2-43. CHGVAR: Conversion between *CHAR and *DEC data types OL209.0Notes:Data type conversion is often used in CL programming to convert decimal data intocharacter data in order to use it in character string operations.In the above example, the decimal fields are shown with signs and decimal points foreducational purposes. Decimal points are actually implied, and the code for a plus or minusnumber occupies half of the low-order byte.2-52 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Concatenation IBM i Combining two *CHAR Variables or Values &FIRST &LAST &NAME MARY *CAT DAVIS MARY DAVIS (|| is equivalent to *CAT) MARY *TCAT DAVIS MARYDAVIS (|< is equivalent to *TCAT) MARY *BCAT DAVIS MARY DAVIS (|> is equivalent to *BCAT) Example: CHGVAR VAR(&NAME) VALUE(&FIRST |> &LAST) © Copyright IBM Corporation 2010 Figure 2-44. Concatenation OL209.0 Notes: The operands in a character string expression must be quoted or unquoted character strings, variables, or the substring (%SUBSTRING or %SST) built-in function. • *CAT: Concatenate without editing. • *TCAT: All trailing blanks in the first character string are truncated, and then the two character strings are concatenated. Any leading blanks of the second operand are not truncated. • *BCAT: Trailing blanks in the first character string are truncated, one blank is inserted, and then the two character strings are concatenated. Any leading blanks of the second operand are not truncated. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-53 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Data type conversion and concatenation example IBM i &NAME &CUSNUMA Resulting message: Customer XYZ CORPORATION, account number 54321, is overdue by 030 days. &DAYSA CHGVAR VAR(&DAYSA) VALUE(&DAYS) CHGVAR VAR(&CUSNUMA) VALUE(&CUSNUM) SNDMSG MSG(Customer *BCAT &NAME *TCAT , account + number *BCAT &CUSNUMA *CAT , is overdue + by *BCAT &DAYSA *BCAT days.) TOMSGQ(ARDEPT) The following variables exist at the start of the program: VARIABLE TYPE LENGTH VALUE &NAME *CHAR 25 XYZ CORPORATION &CUSNUM *DEC (5 0) 54321 &CUSNUMA *CHAR 5 &DAYS *DEC (3 0) 30 &DAYSA *CHAR 3 © Copyright IBM Corporation 2010Figure 2-45. Data type conversion and concatenation example OL209.0Notes:Decimal variables must be converted to character variables before they can be used inmessage text.2-54 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Conditional execution IBM i IF COND relational THEN (command) ( or logical expression ) TRUE IF ELSE CMD(command) THEN FALSE THEN parameter or ELSE command is ELSE optional. © Copyright IBM Corporation 2010 Figure 2-46. Conditional execution OL209.0 Notes: THEN parameter is omitted; ELSE command is specified. • True condition: Control goes to the command after the ELSE statement. • False condition: Execute the command in the ELSE statement. THEN parameter is specified; ELSE command is omitted. • True condition: Execute the command in the THEN parameter. • False condition: Control goes to the command after the IF statement. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-55 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Relational and logical expressions IBM i Expression: (Operand Operator Operand) Result of a relational or logical expression: 1 True or 0 False Operands: Constant, Variable, Another Expression Operators Description < *LT Less Than = *EQ Equal To > *GT Greater Than <= *LE Less Than or Equal To ¬< *NL Not Less Than ¬> *NG Not Greater Than >= *GE Greater Than or Equal To ¬= *NE Not Equal To & *AND True if both operands are 1 | *OR True if both or either operand is 1 ¬ *NOT © Copyright IBM Corporation 2010Figure 2-47. Relational and logical expressions OL209.0Notes:Logical and relational expressions are either true or false. The system represents a truecondition with a 1 and represents a false condition with a 0. These are character values.This figure shows two ways of representing operators. You may use either themathematical symbols or the equivalent English abbreviations to show a relationship.2-56 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty IF examples IBM i 1. IF COND(&RESP *EQ 5) THEN(CALL PGM(CUSINQ)) OR IF (&RESP *EQ 5) CALL CUSINQ 2. IF COND(&AMT *GT 10000) THEN(CALL PGMBIG) ELSE CMD(CALL PGM(PGMSMALL) 3. IF (&A*NE &B) RETURN OR IF (&A =&B) ELSE RETURN 4. IF &IN03 RETURN © Copyright IBM Corporation 2010 Figure 2-48. IF examples OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-57 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook DO group IBM i IF COND(&A *GT 100) THEN(DO) CALL PGM1 CALL PGM2 ENDDO ELSE CMD(DO) CALL PGM3 CALL PGM4 ENDDO CALL PGM5 © Copyright IBM Corporation 2010Figure 2-49. DO group OL209.0Notes:The DO command is valid in the THEN parameter of an IF statement or in the CMDparameter of an ELSE statement. It groups all commands between it and an ENDDOcommand.In this example, either PGM1 and PGM2 are executed or PGM3 and PGM4 are executed,but not both groups. PGM5 is executed in either case.CL program syntax allows indentation for readability.2-58 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Nested IF statements IBM i T T T &RESP=1 &A = 5 &B = N CALL PGMA F F F Keyword form: IF COND(&RESP = 1) THEN(IF COND(&A = 5) THEN(IF + COND(&B = N) THEN(CALL PGM(PGMA)))) Positional form: IF (&RESP = 1) IF (&A = 5) IF (&B = N) CALL PGMA DO, ENDDO form: IF COND(&RESP = 1) THEN(DO) /* #1 */ IF COND(&A = 5) THEN(DO) /* #2 */ IF COND(&B = N) THEN(DO) /* #3 */ CALL PGMA ENDDO /* #3 */ ENDDO /* #2 */ ENDDO /* #1 */ One IF with a compound condition IF COND((&RESP = 1) *AND (&A = 5) *AND (&B = N)) THEN(CALL PGMA) © Copyright IBM Corporation 2010 Figure 2-50. Nested IF statements OL209.0 Notes: This is a flowchart for nested IF statements, representing a complex condition. The coding is shown in three coding styles, all equivalent to the flowchart. If the nested IFs are discarded and replaced with a compound expression, the same logic can be put into a single IF statement. Refer to the last example. Note: The maximum level of nesting for conditional CL commands is 25 statements. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-59 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook PGMB and/or PGMC and/or PGMD IBM i T &A=&B PGMB F IF COND(&A=&B) THEN(CALL PGM(PGMB)) IF COND(&A=&C) THEN(CALL PGM(PGMC)) T &A=&C PGMC IF COND(&A=&D) THEN(CALL PGM(PGMD)) F T &A=&D PGMD F © Copyright IBM Corporation 2010Figure 2-51. PGMB and/or PGMC and/or PGMD OL209.0Notes:This figure shows a structured flow chart and the corresponding control languagestatements. These statements are a series of IF statements. The condition is tested in eachcase. If &A = &B = &C = &D, all three programs, PGMB, PGMC, and PGMD, will be run.2-60 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty PGMB or PGMC or PGMD IBM i &A=&B T PGMB F T &A=&C PGMC F T &A=&D PGMD F IF COND(&A = &B) THEN(CALL PGM(PGMB)) ELSE CMD(IF COND(&A = &C) THEN(CALL PGM(PGMC))) ELSE CMD(IF COND(&A = &D) THEN(CALL PGM(PGMD))) © Copyright IBM Corporation 2010 Figure 2-52. PGMB or PGMC or PGMD OL209.0 Notes: This figure shows a structured flow chart with the corresponding IF and ELSE statements. The second and third IF statements are embedded. When a condition proves true, embedded IF statements that follow are bypassed. This logic is normally found in the programs used in program menus. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-61 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using the SELECT command IBM i SELECT WHEN (condition-1) THEN(command-1) . . . WHEN (condition-n) THEN(command-n) OTHERWISE command-x ENDSELECT 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 © Copyright IBM Corporation 2010Figure 2-53. Using the SELECT command OL209.0Notes:The SELECT command is used to identify one or more conditions and an associated groupof commands to process when that condition is true. A special group of commands mayalso be specified to be processed when none of the stated conditions is true. Only one ofthe groups of commands identified by WHEN or OTHERWISE commands will beprocessed within the group.The general structure of the SELECT command is as follows:SELECTWHEN (condition-1) THEN(command-1)....................................................WHEN (condition-n) THEN(command-n)OTHERWISE command-xENDSELECT2-62 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 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 may 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 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. In the example, 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. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-63 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Branching within a program: GOTO IBM i START: PGM SNDRCVF RCDFMT(MENU) . . . IF (&OPTION = 12) GOTO CMDLBL(END) . . . . . GOTO START END: ENDPGM Statement labels must be unique. © Copyright IBM Corporation 2010Figure 2-54. Branching within a program: GOTO OL209.0Notes:Any command in a CL program may have a statement label. Labels have one to tencharacters and are followed by a colon. A label is used as the target of the GOTOcommand. In this program, when the GOTO START command is executed, control is givento the statement with label START at the top of the program. If &OPTION = 12, the GOTOcommand sends control to the ENDPGM statement.The use of the GOTO statement can lead to unstructured logic (often referred to asspaghetti code) which is difficult to maintain. The flow of your program can be controlledmuch better with the structured operations discussed overleaf.2-64 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using the DOUNTIL and DOWHILE commands IBM i DOUNTIL (&LGL) . . . CHGVAR &INT (&INT + 1) IF (&INT *GT 5) (CHGVAR &LGL 1) ENDDO DOWHILE (&LGL) . . . IF (&INT *EQ 2) (CHGVAR &LGL 0) ENDDO © Copyright IBM Corporation 2010 Figure 2-55. Using the DOUNTIL and DOWHILE commands OL209.0 Notes: 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 ENDDO command. After the group of commands is processed, the stated condition is evaluated. If the condition is true, the DOUNTIL group is exited, and processing resumes with the next command following the associated ENDDO. If the condition is false, the group continues processing with the first command in the group. The logical expression on the COND parameter may 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 body of the DOUNTIL group is run at least one time. If the initial value of the &INT variable is 5 or more, &LGL is set to true the first time, and processing continues 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 continues to be repeated until the value of &INT is greater than 5 and the value of &LGL is changed to true. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-65 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookThe DOWHILE command lets you process a group of commands zero or more times whilethe value of a logical expression is true. The DOWHILE command is used to state acondition 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 thematching ENDDO command. After the group of commands is processed, the statedcondition is evaluated. If the condition is false, the DOWHILE group is exited andprocessing resumes with the next command following the associated ENDDO. If thecondition is true, the group continues processing with the first command in the group.When the ENDDO command is reached, control returns to the DOWHILE command toagain evaluate the condition. The logical expression on the COND parameter may be asingle logical variable or constant, or it must describe a relationship between two or moreoperands; the expression is then evaluated as true or false.When the DOWHILE group is processed, the stated condition is evaluated. If the conditionis true, the group of commands in the DOWHILE group is processed. If the condition isfalse, processing continues with the command following the associated ENDDO command.If the value of &LGL is true, the commands in the DOWHILE group are run until &INT isequal to 2, causing the &LGL variable value to be set to false.2-66 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using the DOFOR command IBM i DOFOR VAR(integer-variable) FROM(initial-value) TO(end-value) BY(integer-constant) . . CHGVAR VAR(&INT2) VALUE(0) DOFOR VAR(&INT) FROM(2) TO(4) BY(1) . . . CHGVAR &INT2 (&INT2 + &INT) ENDDO /* &INT2 = 9 after running the DOFOR group 3 times */ © Copyright IBM Corporation 2010 Figure 2-56. Using the DOFOR command OL209.0 Notes: The 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. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-67 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookWhen the DOFOR group is processed, &INT is initialized to 2, and the value of &INT ischecked to see if it is greater than 4. It is not, so the body of the group is processed. On thesecond iteration of the group, one is added to &INT, and the check is repeated. It is lessthan 4, so the DOFOR group is processed again. On reaching the ENDDO the secondtime, the value of &INT is again incremented by one. &INT now has a value of 4. Since&INT is still less than or equal to 4, the DOFOR group is processed again. On reaching theENDDO the third time, the value of &INT is again incremented by one. This time, the valueis 5, and processing continues with the command following the ENDDO.2-68 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using the ITERATE command IBM i 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 © Copyright IBM Corporation 2010 Figure 2-57. Using the ITERATE command OL209.0 Notes: The 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 skips to the ENDDO of the innermost active DO group. Specifying a label skips to the ENDDO of the DO associated with the label. 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 DOFOR command. If &INT is greater than 99, processing continues with the next command following the first ENDDO. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-69 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookWhen the third IF command is processed and &A is less than zero, processing continueswith the second ENDDO. The value of &LGL is evaluated and, if false, control passes tothe command following the ENDDO. If true, processing resumes with the DOFORcommand following the DOWHILE.2-70 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using the LEAVE command IBM i 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 © Copyright IBM Corporation 2010 Figure 2-58. Using the LEAVE command OL209.0 Notes: The LEAVE command can be used to exit an active DOWHILE, DOUNTIL, or DOFOR group. It provides a structured manner to leave an active group without resorting to the use of the GOTO command. LEAVE is not valid with simple DO command groups. A LEAVE command without a label leaves the innermost active DO group. Specifying a label allows the processing to break out of one or more enclosing groups. 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 command is processed and &A is less than zero, processing continues with the next command following the first ENDDO. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-71 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Branching inside a program: CALLSUBR IBM i Top Bottom Subroutine Stack Level n Level n+1 Level n+2 MAINPGM SBR1 SBR2 PGM SUBR SUBR(SUBR1) . . SUBR SUBR(SUBR2) . . . CALLSUBR SUBR1 CALLSUBR SUBR2 . ........... ........... . . . ENDSUBR . . . . . RTNSUBR . . . . SUBR1 . . ENDSUBR . SUBR2 . CALLSUBR SUBR(SUBR1) RTNVAL(&myrtnvar) ENDPGM DCLPRCOPT SUBRSTACK(25) © Copyright IBM Corporation 2010Figure 2-59. Branching inside a program: CALLSUBR OL209.0Notes:The Call Subroutine (CALLSUBR) command is used in a CL program for passing control toa subroutine that is defined within the same program.The CALLSUBR command has two parameters: Subroutine (SUBR), which contains thename of the subroutine to which control is to be transferred to, and optionally, Return value(RTNVAL), which specifies a variable that will contain the return value from the calledsubroutine. See the following example:CALLSUBR SUBR(SUBR1) RTNVAL(&myrtnvar)The subroutine SUBR1 must be defined in the program by the Subroutine (SUBR)parameter of an SUBR command. The variable &myrtnvar, must be defined as TYPE(*INT)LEN(4) so that it can contain a value from the Return value (RTNVAL) parameter of either aReturn from Subroutine (RTNSUBR) or End Subroutine (ENDSUBR) command found insubroutine SUBR1. If no RTNVAL parameter is defined, the return value from thesubroutine is ignored.2-72 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty The CALLSUBR command can be placed anywhere within the program, 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. The default value for the SUBRSTACK parameter is 99. The valid range for this parameter is 20 to 9999. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-73 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Subroutines IBM i • Simple code block between SUBR and ENDSUBR • Invoked by CALLSUBR command – No argument/parameter passing required – Optional RTNVAL can specify 4-byte *INT variable – No local scoping of subroutine variables – Local scoping of labels – No nesting allowed (subroutines within subroutines) • Return to caller via RTNSUBR or ENDSUBR • Cannot use GOTO to enter or leave the body of a subroutine, OK within a subroutine © Copyright IBM Corporation 2010Figure 2-60. Subroutines OL209.0Notes:SUBRThe Subroutine command is used in a CL program, along with the End Subroutine(ENDSUBR) command, to delimit the group of commands that define a subroutine. TheSUBR command defines the start of a subroutine. Subroutines may not be nested;therefore, an ENDSUBR command must end the current subroutine before the next SUBRcommand starts a new subroutine. A label specified on a SUBR command, or on a null(empty) command preceding the SUBR command, can be used as a target for a Go To(GOTO) command defined in the same subroutine. This GOTO command, when run, willpass control to the first executable statement in the subroutine.ENDSUBRThe End Subroutine command specifies the end of a subroutine, and must be paired with aprevious Subroutine (SUBR) command. When the ENDSUBR command is processed,control is returned to the command immediately following the Call Subroutine (CALLSUBR)2-74 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty command that called the subroutine. If a value is to be returned, such as an error code, the returned value must be able to be stored into a 4-byte signed integer CL variable. The Return value (RTNVAL) parameter can be a variable or constant. If no RTNVAL parameter is defined, the value will default to zero. RTNSUBR The Return from Subroutine (RTNSUBR) command returns control to the command immediately following the Call Subroutine (CALLSUBR) command that called the subroutine. The RTNSUBR command must be used within a subroutine, and multiple RTNSUBR commands may be used in a subroutine. If a value is to be returned, such as an error code, the returned value must be able to be stored into a 4-byte signed integer CL variable. The Return value (RTNVAL) parameter can be a variable or constant. If no RTNVAL parameter is defined, the value will default to zero. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-75 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Branching outside a program: TFRCTL IBM i Top Program Stack Bottom Level n Level n+1 Level n+2 PGMA PGMB PGMC PGM PGM PGM . . . . . . . CALL PGMB CALL PGMC ENDPGM ........... ........... . . . . . . TFRCTL PGMD . . . PGMD PGM . . . RETURN © Copyright IBM Corporation 2010Figure 2-61. Branching outside a program: TFRCTL OL209.0Notes:The Transfer Control (TFRCTL) command calls the program specified in the command,passes control to it, and removes the transferring program from the call stack. Reducingthe number of programs on the call stack can have a performance benefit.When Program PGMB executes TFRCTL PGMD, PGMB is removed from the programstack.Parameters passed with the TFRCTL command must have been received as parameters inthe program containing the TFRCTL command. TFRCTL is only valid within a CL program.The RETURN command in a CL procedure or original program model (OPM) programremoves that procedure or OPM program from the call stack.If the procedure containing the RETURN command was called by a CALLPRC or CALLcommand, control is returned to the next sequential statement after that CALLPRC orCALL command in the calling program.ENDPGM signals the end of the procedure, and returns control to the calling procedure.2-76 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Communicating data to a program with CALL IBM i *PGM: A PGM DCL VAR(&COUNTA) TYPE(*DEC) LEN(3 0) . Jobs Static . Storage Area . CALL PGM(B) + Variables for A PARM( 0 &COUNTA 100 ABC Co.) &COUNTA 005 . *CHAR *DEC . *CHAR Variables for B (32) (15 5) . 006 (32) &IN99 &COUNTB *PGM: B &X PGM PARM(&IN99 &COUNTB &X &CO) &CO DCL &IN99 *LGL . DCL &COUNTB *DEC (3 0) DCL &X *DEC (15 5) . DCL &CO *CHAR (20) . . . . CHGVAR VAR(&COUNTB) VALUE(&COUNTB + 1) . . . © Copyright IBM Corporation 2010 Figure 2-62. Communicating data to a program with CALL OL209.0 Notes: This figure reveals the rules of passing data to a control language program: • Logical variables are either character 1 or 0. • Decimal constants always pass with a length of (15 5), the default length of DCL. • Character constants pass with a 32-position length if the character string is 32 positions or fewer. If the character string is > 32 positions, the exact length of the character string is passed to the CL program. • Variables must be in the same sequence in the PARM parameter of the PGM command of the called program as they are in the PARM parameter of the CALL. When a variable is changed in the called program, it is automatically changed in the calling program. The variables must be defined with the same characteristics in the called program as in the calling program but do not have to have the same names. • When parameters are passed from one CL program to another, no new storage area is allocated in the called program for the variables received as parameters. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-77 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • To pass a number as character value, enclose it in single quotes, for example, 12345 • If the receiving parameter is shorter in length than the sending parameter, results are unpredictable. Character parameters, in this case, are truncated. • Since a program executing a TFRCTL command is removed from the program stack, only variables passed to the program are allowed on the PARM parameter of a TFRCTL command.Caution: Carefully match the type, length, and decimal positions (if numeric) of the sendingand receiving parameters. • Most common call errors - In some cases, decimal numbers are converted to a constant and passed as  (15 5), so use this default when possible.If you pass a character variable that is longer than the declared length of the receivingvariable, the receiving program cannot access the excess length because it will have beentruncated.2-78 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty HLL and CL programs may call each other IBM i CL DCL VAR(&IN98) TYPE(*LGL) DCL VAR(&CUSTZ) TYPE(*DEC) LEN(5 0) CALL PGM( ) PARM(&CUSTZ &IN98) RPG IV D Customer PI D CustZ 5P 0 D Indic N COBOL Linkage Section. 01 Customer PIC S99999 COMP-3. 01 IN98 PIC 1. Procedure Division Using Customer, IN98. © Copyright IBM Corporation 2010 Figure 2-63. HLL and CL programs may call each other OL209.0 Notes: From the standpoint of a calling CL program, there is no difference in calling an RPG IV, COBOL, CL, C, or any other type of program. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-79 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook2-80 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 2.3. i application development tools © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-81 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook i application development tools IBM i After completing this topic, you should be able to: • Describe the application development toolset for IBM i © Copyright IBM Corporation 2010Figure 2-64. i application development tools OL209.0Notes:2-82 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty IBM Rational Developer for Power Systems IBM i • IBM Rational Developer for Power Systems product family includes: – Remote Systems Explorer (RSE) – Remote Systems LPEX Editor – RPG, COBOL, CL tools . . . – i Projects – Visual Designers: Screen Designer and Report Designer ... – Application Diagram • LPEX Editor is a set of integrated development tools that allow you to: – Create, edit, compile, and maintain your source code – Debug programs using a PC connected to an i server – Completely organize your programming projects © Copyright IBM Corporation 2010 Figure 2-65. IBM Rational Developer for Power Systems OL209.0 Notes: IBM Rational Developer for Power Systems Software (RDP), formerly named IBM Rational Developer for i (RDi), provides integrated development and debug tools for IBM i and AIX systems. This software helps developers create and maintain IBM i applications with rich source editing features, visual design and analysis tools, and compile/build error feedback. At the heart of this software is the LPEX Editor. With the LPEX Editor, programmers can use DDS to define display files, printer files and database files. LPEX is also used to key and compile RPG and COBOL programs RSE is similar to PDM in that it allows the developer to drill down into the QSYS file system, or use filters to list specific objects within the QSYS file system. RSE goes well beyond PDM. It also allows exploration of the i jobs and commands. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-83 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Rational support for i 7.1 and beyond IBM i • Rational Developer for Power – Feature: RPG and COBOL Development for i • eclipse-based tools for RPG/COBOL development • New print designer & support for language RPG enhancements Developer Java • Replaces Rational Developer for i (RDi) Developer – COBOL and C/C++ options for AIX • Rational Team Concert for Power – Collaborative software development, automate best EGL COBOL practices Developer Developer – Integrated source control and build management – IBM i or AIX repository options • Rational Application Developer – Robust Java development environment C/C++ Developer – Web/Web Services development integration – EJB and J2EE fully supported • Rational Development Studio – Rebranding for WebSphere Development Studio – Provides ILE & OPM compliers + traditional development tools – New language functions have been added to ILE Compilers Eclipse-based development tools can improve programmer productivity and provide a familiar development environment for new employees © Copyright IBM Corporation 2010Figure 2-66. Rational support for i 7.1 and beyond OL209.0Notes:Additional development and collaboration tools in the Rational suite are updated for i 7.1and have been enhanced to support AIX in addition to IBM i.2-84 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Rational Developer for Power IBM i © Copyright IBM Corporation 2010 Figure 2-67. Rational Developer for Power OL209.0 Notes: For more information on Rational Developer for Power, see the following web site: http://www-01.ibm.com/software/rational/products/rdp/ © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-85 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook WDS/RDi 7.5/RDP 7.5 IBM i I V5.4 I V6.1 I V7.1 5722WDS 5761WDS 5770WDS RDP Feature: ILE Compilers *Base Option 31 ILE RPG RDP (New) Option 21 ADTS Option 35 ILE RPG *PRV Compiler Option 31 ILE RPG Option 41 ILE COBOL (replaces RDi) Option 32 S/36 Option 45 ILE COBOL *PRV Compiler Option 51 ILE C Compatible RPGII Option 52 ILE C++ Option 33 S/38 Option 56 IXLC for C/C++ Compatible RPGII RDi for SOA Option 34 RPG/400 RDi/SOA + RAD + HATS Option 35 ILE RPG *PRV Feature: Heritage Compilers Compiler Option 32 S/36 Compatible RPG II RBD + EGL Option 41 ILE COBOL Option 33 S/38 Compatible RPG II Option 34 RPG/400 (RPG III)_ Option 42 S/36 Option 42 S/36 Compatible COBOL Compatible COBOL Option 43 S/38 Compatible COBOL Option 43 S/38 Option 44 OPM COBOL RDi Compatible COBOL RDi (replaced by RDP) Option 44 OPM COBOL Option 45 ILE COBOL Feature: ADTS *PRV Compiler Option 21 ADTS Option 60 Workstation Tools Option 51 ILE C Option 52 ILE C++ Option 56 IXLC for C/C++ © Copyright IBM Corporation 2010Figure 2-68. WDS/RDi 7.5/RDP 7.5 OL209.0Notes:There is one consolidated Application Development product available for i programmers.The product is called Rational (WebSphere) Development Studio (WDS), which includesthe following:i compilers • ILE RPG • ILE COBOL • ILE C • ILE C++Application Development Tool Set • Source Entry Utility (SEU) • Screen Design Aid (SDA) • Report Layout Utility (RLU)2-86 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty • Data File Utility (DFU) • Character Generator Utility (CGU) • Advanced Printer Function (AFP) • Programming Development Manager (PDM) • Interactive Source Debugger (ISDB) • File Compare and Merge Utility (FCMU) WDS at IBM i releases 5.4, 6.1 and 7.1 all cooperatively work with the client PC programs IBM Rational Developer for i (RDi) and Rational Developer for Power Systems (RDP). RDi includes the following: • LPEX Editor • Remote System Explorer • Debugger • i Project Organizer RDP includes the following: • LPEX Editor • Remote System Explorer • Debugger • i Project Organizer • Screen Designer • Report Designer Rational Developer for i for SOA Construction is additional PC-licensed code that, when purchased, adds the following features: • Rational Business Developer • Host Access Transformation Services (HATS) Toolkit • Rational Application Developer (RAD) • Rational Business Developer (RBD) • Enterprise Generation Language (EGL) RDi for SOA can be used to modernize existing RPG and COBOL business applications to the web, mobile devices or into web services. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-87 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookStarting with IBM i 6.1, WDS was packaged into three separately priced optional features:ILE compilers, heritage compilers, and ADTS (legacy development tools). Modernizedshops now have the option of ordering the appropriate i optional features of WDS as wellas the appropriate PC client software such as RDP or RDi (to use with WDS) and RDi SOAat additional costs.Entitlement on 5761-WDS and 5770-WDS ILE Compilers, Heritage Compilers, and ADTSfeatures are based on a maximum number of users per processor tier.2-88 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Tool choices: Editors (1 of 2) IBM i Source Entry Utility (i Server) –Create and maintain program source members –Create and maintain database file definition source –5250 green screen interface –Can invoke using STRSEU or from within Program Development Manager PDM © Copyright IBM Corporation 2010 Figure 2-69. Tool choices: Editors (1 of 2) OL209.0 Notes: You can use the Source Entry Utility (SEU) to work with source members in source physical files, and the records contained in source members. With SEU, you can perform operations such as: • Create members • Edit members • Print members • Copy records into a member from another member or spooled file These source members can include: • ILE RPG • File description (DDS) • Screen display file source (DDS) • Report definition source (DDS) © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-89 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookData description specifications (DDS) is a common definition used for files, displays, andreports. Because the i is a database system, it is possible to define fields in one place andthen reference that definition (through DDS) to define other files, displays, and reports.In this example, we show you some of the source of a CL program source member. Youcan work with the member directly on the i system.2-90 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Tool choices: Editors (2 of 2) IBM i LPEX Editor (Windows PC) –Part of RDP (RDi) set of client tools –Can be connected to i server or disconnected –Uses GUI interface –Tokenizes source and uses color to differentiate tokens © Copyright IBM Corporation 2010 Figure 2-70. Tool choices: Editors (2 of 2) OL209.0 Notes: This is the same source program we showed in the SEU example. You can use whichever tool you prefer or use them interchangeably. With the LPEX Editor, you can do the following: • Access local and i source files seamlessly • Download i source members to the PC and then maintain them in disconnected mode • Work concurrently with multiple edit sessions as well as multiple views of the same source member • Navigate through multiple programs and subroutines in one or more source members • Search and compare multiple files at once © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-91 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook What is RDi/RDP/RSE? IBM i • A complete application development environment for developing i host applications on your Windows PC. • An integrated set of development tools for third generation language 3GL programming that builds on existing developer skills and provides significant productivity enhancements for: – Edit /compile cycle – DDS design – Debugging – Working disconnected © Copyright IBM Corporation 2010Figure 2-71. What is RDi/RDP/RSE? OL209.0Notes:RDP/RDi is not a code generator. You still edit, compile, and debug your i programs. Thetools available under the LPEX Editor help to reduce the time it takes to produce andmaintain your applications.2-92 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty LPEX editor interface IBM i Sequence numbers Syntax checking Format line © Copyright IBM Corporation 2010 Figure 2-72. LPEX editor interface OL209.0 Notes: The LPEX Editor of RDi/RDP has the standard features of a Windows-based application: • Cut, copy, and paste • Menus • Tool bar • Resizeable window It provides i specific features such as: • Member locking when you open a source member for editing. • Verification of object authority to prevent users from editing source for which they are not authorized. The area at the top of the editor is used as a ruler for column-sensitive languages. The ruler helps keep track of columns and position of the cursor. The ruler changes to reflect the type of line you are on. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-93 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookOther features are also available: • Syntax errors are marked immediately. Interactive (or demand) syntax checking allows you to verify directly your code and as help if needed (F1). • The use of color to display the tokens makes reading source code easier. A token is a language construct, for example, specification fields for RPG, constructs in COBOL, columns in DDS, functions in C, and commands and labels in CL. Each token in your file is displayed in a different color to facilitate reading the source. • Multiple files can be open at the same time, and you can switch to a different one using the quick file access. You can even do a search and replace on all loaded files.The LPEX Editor has a number of navigational options that help you to easily find your waythrough the code: • Searching and replacing • Creating and finding marks • Locating code using line numbers. Press CTRL+L or type a line number in the prefix area. This takes you to that line. Locating a line number works in both directions, up and down. • Comment lines2-94 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty SEU: Similar features, prompting CL IBM i Use your prompt window for the prompting of CL commands © Copyright IBM Corporation 2010 Figure 2-73. SEU: Similar features, prompting CL OL209.0 Notes: Prompting CL brings up a separate window for you to enter the statement. Place the cursor on the command you would like to prompt and press F4. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-95 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Multiple edit windows IBM i © Copyright IBM Corporation 2010Figure 2-74. Multiple edit windows OL209.0Notes:The Editor allows several members to be edited. Each time you open a member with theLPEX Editor, a tab is added to your view, and you can highlight any member you like inorder to edit it. This way, multiple members from the same or different files can beviewed/edited concurrently.2-96 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Program generator IBM i © Copyright IBM Corporation 2010 Figure 2-75. Program generator OL209.0 Notes: When you Compile -> Compile (Prompt) -> CRTBNDCL, you are presented the appropriate dialog of compile options for the selected source member. In this example, the source member to be compiled is of type CLLE. You can request all parameters by checking the All Parameters box and hence change any of the available parameters. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-97 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook LPEX editor: Settings IBM i © Copyright IBM Corporation 2010Figure 2-76. LPEX editor: Settings OL209.0Notes:Basic customization can be done from the Window -> Preferences menu options.Basic Editor window customization, like font, font style and size, can be chosen.2-98 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty LPEX editor summary IBM i • Integrated edit, verify, compile cycle • Token highlighting • Syntax checking • Error feedback from verify and compile • Functions like Navigator, file compare, and so forth • Improved developer productivity • Builds on existing skills • Lots of online Help • Offloaded application development from host • Customizable and extensible © Copyright IBM Corporation 2010 Figure 2-77. LPEX editor summary OL209.0 Notes: The most frequently used editor is the Source Entry Utility (SEU), which is part of the Rational Development Studio for i software. This tool is used on the i. The PC-based LPEX Editor, on the other hand, allows for more productive use of client functions. © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-99 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint (1 of 2) IBM i 1. An implicit declaration of variables occurs a. when the DCL command is used to define variables. b. whenever CRTBNDCL is used to compile a CLLE source member. c. when the DCLF command is used to declare a file. d. when CRTCLPGM is used to compile a CLP source member. 2. The CHGVAR command can be used a. for arithmetic calculations. b. for converting data from one data type to another. c. for making character string data assignments. d. for all of the above. 3. Logical and relational expressions are either true or false. The system represents a true logical condition with a ____, and represents a false condition with a ____. © Copyright IBM Corporation 2010Figure 2-78. Checkpoint (1 of 2) OL209.0Notes:2-100 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint (2 of 2) IBM i 4. Which of the following is true when passing data to a CL program? a. Decimal constants always pass with a length of (15 5). b. Variables must be in the same sequence in the calling and called programs. c. Numbers passed as a character value, are enclosed in single quotes: ‘12345’. d. All of the above. 5. True or False: High level language (HLL) programs may call CL programs. © Copyright IBM Corporation 2010 Figure 2-79. Checkpoint (2 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-101 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Workstation exercises IBM i • Lab 2: Write a CL program (required) – Use LPEX Editor or SEU • Lab 3: Initial program (required) – Prerequisite for all other labs • Lab 4: Menu-like program (required) • Lab 5: Call/Transfer control (required) • Lab 6: Calculator (required) – CALCXXX and ADDXXX – Other programs optional © Copyright IBM Corporation 2010Figure 2-80. Workstation exercises OL209.0Notes:2-102 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit summary IBM i Having completed this unit, you should be able to: • Understand the concepts of object, library and library list • Describe how the commands are used in CL programs • Describe the application development tools • Write basic CL programs © Copyright IBM Corporation 2010 Figure 2-81. Unit summary OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 2. Basic CL programming 2-103 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook2-104 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 3. Program creation and debugging What this unit is about Program testing includes debug mode, breakpoints, and the options available on the CRTBNDCL command. What you should be able to do After completing this unit, you should be able to: • Describe how to create and call ILE modules, programs, and service programs • State the purpose of the parameters on the CRTBNDCL command • Use interactive source debugging facilities How you will check your progress • Machine exercises • Checkpoint questions © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit objectives IBM i After completing this unit, you should be able to: • Describe how to create and call ILE modules, programs, and service programs • State the purpose of the parameters on the CRTBNDCL command • Use interactive source debugging facilities © Copyright IBM Corporation 2010Figure 3-1. Unit objectives OL209.0Notes:3-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 3.1. Creating program objects © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Creating program objects IBM i After completing this topic, you should be able to: • Compile CL program objects • Describe the difference between OPM and ILE CL programs © Copyright IBM Corporation 2010Figure 3-2. Creating program objects OL209.0Notes:3-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty OPM versus ILE IBM i OPM ILE Single language Mixed language focus focus Common error handling Language-specific + error handling Language-specific error handling Compilation results Compilation results in a running *MODULE or program *PGM Compile, run Compile, bind, run CRTCLPGM PDM Option 14 CRTBNDCL Member Type CLP (Compile) Member Type CLLE Command (CL) syntax EXACTLY the same © Copyright IBM Corporation 2010 Figure 3-3. OPM versus ILE OL209.0 Notes: When programming on the i, you hear the terms OPM and ILE. The programming concepts and compilation commands that have been covered are considered part of the newer model called Integrated Language Environment (ILE). The i also supports the legacy method of compiling programs called the Original Program Model (OPM). The OPM focuses on a single programmable language and offers error handling specific to that language. For example, interactions between RPG and COBOL programs are difficult to predict. OPM compiles result in executable program objects that can be used together to create robust application processes. The ILE model allows for programs written in different languages to run as a single unit. The output of an ILE compiler is a non-executable module. One or more modules are then bound together to form an executable program. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookILE also allows for • Modularity • Better code optimization • More extensive control over resourcesDifferent commands and compilers are used for ILE programming. When programming inILE CL, the source member type is CLLE, and the compile command is CRTBNDCL.The main advantages of ILE come into play when you write programs in high-levellanguages or your programs are complicated (for example, involving multiple calls to otherprograms). For the simple CL programs, the OPM model could continue to be used.However, ILE provides optimal system resource utilization. ILE is the recommendedmethod for building your CL application programs in order to take advantage of systemresource utilization, improved application support and function.A *MODULE is not executable unless it becomes a part of a program (*PGM). A programmay consist of one or more *MODULEs.We discuss some of these concepts in more detail later in this unit.3-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Create Bound CL Program (CRTBNDCL) (1 of 2) IBM i © Copyright IBM Corporation 2010 Figure 3-4. Create Bound CL Program (CRTBNDCL) (1 of 2) OL209.0 Notes: The Create Bound Control Language Program (CRTBNDCL) command creates an Integrated Language Environment (ILE) control language (CL) program from the specified (CLLE) source code. The command is valid in batch and interactive jobs, and in both compiled and interpreted CL. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Create Bound CL Program (CRTBNDCL) (2 of 2) IBM i <<<< © Copyright IBM Corporation 2010Figure 3-5. Create Bound CL Program (CRTBNDCL) (2 of 2) OL209.0Notes:Debugging view (DBGVIEW)Specifies which level of debugging is available for the compiled program and which sourceviews are available for source-level debugging.The possible values are: • *STMT: The compiled program can be debugged using program statement numbers and symbolic identifiers. • *ALL: All of the debug options for debugging the compiled program can be used. The source and debug listing views are generated. • *SOURCE: The source view for debugging the compiled program is generated. • *LIST: This listing view for debugging the compiled program is generated. • *NONE: None of the debug options for debugging the compiled program is available.3-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Declare Processing Options (DCLPRCOPT) IBM i © Copyright IBM Corporation 2010 Figure 3-6. Declare Processing Options (DCLPRCOPT) OL209.0 Notes: The Declare Processing Options (DCLPRCOPT) command allows you to define compiler options as well as the number of subroutines that are allowed in the subroutine stack during program execution. You can use this command to set compiler parameters in your CL source program instead of specifying the same parameters on the CL command used to invoke the compiler (CRTBNDCL, CRTCLMOD, and CRTCLPGM). Setting a parameter with the DCLPRCOPT command overrides that same parameter value (or default) set via the compile command parameter. Your compile listing will not show the parameter values set by the DCLPRCOPT command. The first page of your compile listing will show the compiler parameters passed in from the CL command used to invoke the CL compiler. Any of these parameters overridden by a DCLPRCOPT command will affect the generated CL program, but will not be reflected on the first page of the compiler listing. Some parameters and parameter values only apply to the original program model (OPM) CL compiler or the integrated language environment (ILE) CL compiler. Parameters or values specified on DCLPRCOPT which are not applicable to the CL compiler invoked to compile the CL source program, are ignored. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookThis command is valid only within a CL program or CL module. All declare commands(DCL, COPYRIGHT, DCLF, and DCLPRCOPT) must follow the PGM (Program) commandand must precede all other commands in the program. The four types of declarecommands can be intermixed in any order. Only one DCLPRCOPT command is allowed inyour source code by the CL compiler.The following are examples of the parameters that can be changed with DCLPRCOPT: • LOG • ALRTVRSC • TEXT • USRPRF • SUT • DFTACTGRP • BNDSRVPGM • BNDDIR3-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Create CL Program (CRTCLPGM) (1 of 2) IBM i © Copyright IBM Corporation 2010 Figure 3-7. Create CL Program (CRTCLPGM) (1 of 2) OL209.0 Notes: The Create CL Program (CRTCLPGM) command creates a control language (CL) program from the specified (CLP) source code. The command is valid in batch and interactive jobs, and in both compiled and interpreted CL. Option (OPTION) • Specifies the types of output listings created when this command is processed, and if a program is created when this command is processed. • You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase + for more values, and press the Enter key. • Possible values are: - *SRC or *SOURCE • The compiler creates a listing of the source input used to compile the program. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook - *NOSRC or *NOSOURCE • A complete compiler source listing is not created; only compiler errors are listed. - *XREF • The compiler creates a cross-reference listing of references to variables or labels in the source. If *NOSOURCE is specified, *NOXREF is always assumed. - *NOXREF • No cross-reference listing of references to variables and data items in the source is created. - *GEN • The compiler creates a program and places it in the appropriate library. *NOGEN • No program is created. The compiler is to syntax check the source and (if *SOURCE is specified) produce a source listing. - *NOSECLVL • No second-level message text will be printed. - *SECLVL • Second-level text is printed along with first-level text for compiler errors. - *NOSRCDBG • Source-level error and debug information is not generated. - *SRCDBG • The compiler generates source-level error and debug information. An event file is created even if the compiler completes the process without error. - *NOLSTDBG • A listing view or listing-level debugging information is not generated. Source-level error information is not created unless *SRCDBG is specified. *LSTDBG The compiler generates a listing view, source-level error information, and listing-level debugging information for use with the source-level debug function of the system debugger (STRDBG OPMSRC(*YES)) to debug OPM programs. Note: *SRCDBG or *LSTDBG is required in order to use the source debugger.3-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Create CL Program (CRTCLPGM) (2 of 2) IBM i © Copyright IBM Corporation 2010 Figure 3-8. Create CL Program (CRTCLPGM) (2 of 2) OL209.0 Notes: Allow RTVCLSRC (ALWRTVSRC) Specifies whether source for the CL program is saved with the program. Source that is saved can be retrieved later by using the Retrieve CL Source (RTVCLSRC) command. Though pictured here on the CRTCLPGM command, this parameter can also be specified on the CRTBNDCL and the CRTCLMOD commands. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL compile listing (1 of 3) IBM i *SOURCE <<<< © Copyright IBM Corporation 2010Figure 3-9. CL compile listing (1 of 3) OL209.0Notes:This information appears if OPTION(*SOURCE) is specified and is called the prologue.The parameters from the CRTBNDCL command are printed.Note: On the compile command, we accepted the default debug option ofDBGVIEW(*STMT). We may need to change this option should program debuggingbecome necessary.3-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty CL compile listing (2 of 3) IBM i *SOURCE © Copyright IBM Corporation 2010 Figure 3-10. CL compile listing (2 of 3) OL209.0 Notes: The source view lists the program coding and any associated compile errors. You can request more detailed text for the error messages by specifying OPTION(*SECLVL) on the CRTBNDCL command. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CL compile listing (3 of 3) IBM i *XREF © Copyright IBM Corporation 2010Figure 3-11. CL compile listing (3 of 3) OL209.0Notes:OPTION(*XREF) produces a cross-reference listing, as shown in this figure.Notice that the field names are listed first, followed by the statement numbers where thosefields are defined. Also shown are the field type, length, and all of the statements thatreference that field.Following that is a cross-reference of statement labels, showing where they are definedand referenced.The end of the listing shows a summary of the messages generated by the compiler.3-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Message severity codes IBM i Severity Description 00 Information 10 Warning 20 Error 30 Severe error 40 Severe error; Should not proceed Abnormal termination of job or program 50 60 System status 70 Device integrity 80 System alert 90 System integrity 99 Action © Copyright IBM Corporation 2010 Figure 3-12. Message severity codes OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook3-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 3.2. Debugging CL programs © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Debugging CL programs IBM i After completing this topic, you should be able to: • Use the source debugger to diagnose program errors © Copyright IBM Corporation 2010Figure 3-13. Debugging CL programs OL209.0Notes:3-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Debugging a compiled program IBM i Suppose program compiles, but functions incorrectly: Use source debugger EXAMPLE: Calculator program in exercise CALL CALCBUGXXX (4 ADD 3) • Expected result: 00000000004.00000 PLUS 00000000003.00000=0000000007.00000 • Actual result: Invalid Operation Code • Why did this occur? How do we identify the cause? • Inspect source > Debug if necessary © Copyright IBM Corporation 2010 Figure 3-14. Debugging a compiled program OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-21 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Before beginning a debug session IBM i In order to use the source debugger, the program must be compiled • ILE CL: Programmer chooses debugging views for parameter DBGVIEW: – Statement number only : *STMT (default) – Source from original source file : *SOURCE – Compiler-generated listing : *LIST – Source and debug listings: *ALL – No debugging capability : *NONE • OPM CL: Programmer chooses for parameter OPTION: *SRCDBG © Copyright IBM Corporation 2010Figure 3-15. Before beginning a debug session OL209.0Notes:When the *NONE option for Debug View is specified, the DUMP operation code is notsupported.Note that debug data can be removed with CHGMOD or CHGPGM. Debug data can beremoved without removing the ability to retranslate the program.If source view is chosen, the source member must be available at the time of the debugsession.The *LIST option saves a copy of the source listing report with the program object.Note also that the storage requirements for a module or program vary somewhatdepending on the type of debug data included with it. The following values for theDBGVIEW parameter are listed in increasing order based on their effect on secondarystorage requirements:1. *NONE2. *STMT3-22 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 3. *SOURCE 4. *LIST 5. *ALL If you are debugging a program that was created from source in a different library, or the source member is named differently from the *PGM object, you may have to OVRDBF FILE(QCLLESRC) or use the QLICOBJD API to work with the source. The debugger will not find the source on its own unless the name and library match where the program object is located. You cannot specify where the source member is located in the STRDBG command. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-23 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Debug procedure IBM i STRDBG command works for ILE programs as well as OPM 1. STRDBG to enter debug session 2. View source 3. BREAK to add breakpoints 4. CALL program 5. Monitor the flow of the program 6. CLEAR to clear breakpoints 7. EVAL to display or change variables 8. ATTR to display attributes of variables 9. ENDDBG to close debug session 10. Change program source 11. Recompile program 12. Test program © Copyright IBM Corporation 2010Figure 3-16. Debug procedure OL209.0Notes:If breakpoints are not added when the source is first displayed, you need to add thembefore calling the program. Otherwise, it simply executes normally without stopping. Youmay remedy the situation either of two ways: • DSPMODSRC and add breakpoints • ENDDBG and start over3-24 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Start Debug (STRDBG) (1 of 2) IBM i Start Debug (STRDBG) Type choices, press Enter. Program . . . . . . . . . . . . PGM > CALCBUGXXX Library . . . . . . . . . . . *LIBL + for more values __________ *LIBL Default program . . . . . . . . DFTPGM *PGM Maximum trace statements . . . . MAXTRC 200 Trace full . . . . . . . . . . . TRCFULL *STOPTRC Update production files . . . . UPDPROD *NO OPM source level debug . . . . . OPMSRC > *YES Service program . . . . . . . . SRVPGM *NONE Library . . . . . . . . . . . + for more values More... F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 3-17. Start Debug (STRDBG) (1 of 2) OL209.0 Notes: CALCBUGXXX is the default program on succeeding commands, DFTPGM(*PGM). Note: OPMSRC(*YES) is required for non-ILE programs so that the program source can be viewed during debugging. This parameter would normally be left to the default value *NO for ILE programs. The Start Debug (STRDBG) command puts a job into debug mode and, optionally, adds as many as 20 programs, 20 service programs, and 20 class files to debug mode. It also specifies certain attributes of the debugging session. For example, it can specify whether database files in production libraries can be updated while in debug mode. The Change Debug (CHGDBG) command can be used later in the job to change the attributes of the debug mode Also, OPM programs can be added to or removed from the debugging session if they are specified in the Add Program (ADDPGM) or Remove Program (RMVPGM) commands. OPM programs added with the ADDPGM command will be in the OPM debug environment. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-25 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookThe End Debug (ENDDBG) command ends debug mode for a job, removes all breakpointsand traces, clears any trace data, and removes all programs from debug mode. Thiscommand cannot be entered when one or more of the programs in the call stack arestopped at a breakpoint.Default program (DFTPGM) • Specifies the name of the OPM program to use as the default program during debug mode. The program specified here is used as the default program for any of the other debug commands for which the user specified a value of *DFTPGM for the Program prompt (PGM parameter). That is, is a default program was previously specified, this parameter can change it. • This parameter is applicable only in the OPM environment.Note: If OPMSRC(*YES) is specified, the OPM program may be added to either the OPMdebug environment or the ILE debug environment. If added to the ILE debug environment,then it cannot be a default program for the OPM debug environment.Update production files (UPDPROD) • Specifies whether database files in a production library can be opened for updating records, or for adding new records, while the job is in debug mode. If not, the files must be copied into a test library before trying to run a program that uses the files. • This parameter is applicable in both OPM and ILE environments. • Possible values are: - *NO • Database files in production libraries cannot be updated while the job is in debug mode. Database files can be opened for reading only. This protects database files from unwanted updates while a program is being debugged. The exception to this is starting debug mode after a production library is already opened. If this value is specified, some commands, which may include function keys, menu options, and pull-downs, may not work properly. - *YES • Database files in production libraries can be updated while the job is in debug mode.OPM source level debug (OPMSRC) • Specifies that OPM program are debugged using the system source debug support (same as ILE source debug). • This parameter is valid for OPM CL, OPM RPG and OPM COBOL programs that were created with OPTION(*SRCDBG) with CRTCLPGM, CRTRPGPGM, and CRTCBLPGM commands. Additionally, this parameter is valid for OPM RPG and OPM COBOL programs that were created with OPTION(*LSTDBG) with the CRTRPGPGM, CRTCBLPGM, CRTSQLRPG, CRTSQLCBL, and CRTRPTRPG commands. If the3-26 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty OPM program is not CL, RPG, or COBOL and was not compiled with a valid debug option, then this parameter is ignored. • This parameter is applicable in both OPM and ILE environments. • ILE functions now operate OPM programs. For example, source level debugging. • The possible values are: - *NO • OPM debug functions are used for OPM programs. - *YES • ILE debug functions are used for OPM programs. Service program (SRVPGM) • Specifies the qualified names of up to 20 service programs to debug in the job. Before a service program can be debugged, its name must be specified on this parameter or the Display Module Source (DSPMODSRC) command. • This parameter is applicable only in the ILE environment. • You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase + for more values, and press the Enter key. • The possible values are: - *NONE • No service program names are specified at the start of the debugging session. The Display Module Source (DSPMODSRC) command can be used to add service programs later. - service-program-name • Specify the names of up to 20 service programs to debug. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-27 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Start Debug (STRDBG) (2 of 2) IBM i Start Debug (STRDBG) Type choices, press Enter. Class . . . . . . . . . . . . . CLASS *NONE + for more values Additional Parameters Display module source . . . . . DSPMODSRC *PGMDEP Source debug program . . . . . . SRCDBGPGM *SYSDFT Library . . . . . . . . . . . Unmonitored message program . . UNMONPGM *NONE Library . . . . . . . . . . . Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 3-18. Start Debug (STRDBG) (2 of 2) OL209.0Notes:Class (CLASS) • Specifies the names of up to 20 class files to debug in the job. Before a class file can be debugged, its name must be specified on this parameter or the Display Module Source (DSPMODSRC) command. • This parameter is applicable only in the ILE environment. • You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase + for more values, and press the Enter key. • The possible values are: - *NONE • No class files are specified at the start of the debugging session. The Display Module Source (DSPMODSRC) command can be used to add class files later. • Specify the names of up to 20 class files to debug.3-28 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Display module source (DSPMODSRC) • Specifies whether the first display of the source debug program is shown when this command is processed and no errors occur. • This parameter is applicable only in the ILE environment. • The possible values are: - *PGMDEP • The appearance of the source debug program display is dependent on the programs specified on the Program prompt (PGM parameter). If any of the programs are ILE programs, the display is shown. If any of the programs are OPM programs with source debug data and OPMSRC(*YES) is specified, the display is shown. If all of the programs are OPM programs and OPMSRC(*NO) is specified, the display is not shown. - *NO • The first display of the source debug program is not shown. - *YES • The first display of the source debug program is shown. Source debug program (SRCDBGPGM) • Specifies the source debug program to be used. • This parameter is applicable only in the ILE environment. • The possible values are: - *SYSDFT • The system source debug program is used. - program-name • Specify the name of the program to be used to debug programs. Unmonitored message program (UNMONPGM) • Specifies the qualified name of the user-supplied program called when a message that is not monitored occurs in the job being debugged. When the program specified is called, it is passed parameters that identify the program name, the recursion level, the high-level language statement identifier, the machine instruction number at which the breakpoint occurred, the message that was not monitored, the message data, the length of the message data, and the message reference key. • This parameter is applicable only in the OPM environment. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-29 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Display Module Source IBM i Display Module Source Program: CALCBUGXXX Library: OL20V9LIB 1 CALCBUGXXX: PGM PARM(&NBR1 &OP &NBR2) 2 DCL &NBR1 *DEC /* 1ST NUMBER * 3 DCL &NBR1A *CHAR 17 /* 1ST NUMBER ALPHA * 4 DCL &OP *CHAR 2 /* OPERATION * 5 DCL &NBR2 *DEC /* 2ND NUMBER * 6 DCL &NBR2A *CHAR 17 /* 2ND NUMBER ALPHA * 7 DCL &RESULT *DEC /* NUMERIC ANSWER * 8 DCL &RESULTA *CHAR 17 /* ALPHA ANSWER * 9 DCL &RESPONSE *CHAR 75 /* ANSWER TO USER * 10 DCL &VERB *CHAR VALUE(AS A PERCENT OF) 11 CHGVAR &NBR1A &NBR1 /* CONVERT TO ALPHA * >> 12 CHGVAR &NBR2A &NBR2 13 IF (&OP=MLT) CALL MLTBUGXXX (&NBR1 &NBR2 &RESULT &VERB 14 ELSE IF (&OP=DIV) CALL DIVBUGXXX (&NBR1 &NBR2 &RESULT &VERB 15 ELSE IF (&OP=SUB) CALL SUBBUGXXX (&NBR1 &NBR2 &RESULT &VERB More... Debug . . . BREAK 12 F3=End program F6=Add/Clear breakpoint F10=Step F11=Display variable F12=Resume F17=Watch variable F18=Work with watch F24=More keys © Copyright IBM Corporation 2010Figure 3-19. Display Module Source OL209.0Notes:When you issue the command STRDBG for the program, the source code is displayed.Here are some things that you can do to set up your debug session for this (or any specificprogram): • Position cursor on a line and press F6 to add or remove a breakpoint. • Position cursor on a variable name and press F11 to see its value. • Press F10 to step through execution of the code one source line at a time or enter step on the debug command line.You can see a Debug command line. You do not enter system commands on this line. Youmay only enter special ILE debug commands.Typically, to set a breakpoint, position your cursor on a line on the screen and press F6.The line number highlights on the screen to indicate a breakpoint setting. Alternatively, youcould use the BREAK command to set breakpoints by statement number (the one listed onthe far left).3-30 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Positioning your cursor on (or near) a variable name and pressing F11 displays the variables value at the bottom of the screen. The F10 key steps through program execution one line of source code at a time. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-31 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Debug command examples: Valid during program execution IBM i 1. EVAL &DEC1 Result: Value of &DEC1 is displayed 2. EVAL &DEC1=101.5 Result: &DEC1=101.5 3. EVAL &CHAR1=EXAMPLE EVAL &CHAR2 = %SUBSTR(&CHAR1 3 2) Result: &CHAR2=AM 4. EVAL &IN03=1 Result: &IN03=1 © Copyright IBM Corporation 2010Figure 3-20. Debug command examples: Valid during program execution OL209.0Notes:3-32 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Display module source function keys IBM i • F1=Help • F15=Select view • F3=End program • F16=Repeat find • F5=Refresh • F17=Watch variable • F6=Add/Clear breakpoint • F18=Work with watch • F9=Retrieve • F19=Left • F10=Step • F20=Right • F11=Display variable • F21=Command line • F12=Resume • F22=Step into • F13=Work with module • F23=Display output breakpoints • F24=More keys • F14=Work with module list © Copyright IBM Corporation 2010 Figure 3-21. Display module source function keys OL209.0 Notes: Some of these function keys are only valid during program execution. Page Down (Roll Up) • Moves forward to show additional information for this display. Page Down (Roll up) shows the next group of items until you reach the end of the information. Page Up (Roll Down) • Moves backward to show additional information for this display. Page Up (Roll Down) shows the previous group of items until you reach the beginning of the information. F1=Help • Provides additional information about using the display or a specific field on the display. F3=End program • Stops the source debugger and returns to the previous menu or display. If a program is running, the program ends. However, breakpoints set in the module remain set, and the © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-33 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook session remains in debug mode. Any watches set on variables in the program remain set to the storage addresses the variables occupied when the watches were set. • If this function key is used for a program running in a job being serviced, the program is not ended. The debugger returns to the previous menu or display.F5=Refresh • Shows the display you are viewing with updated information.F6=Add/Clear breakpoint • If no breakpoint exists on the source line where the cursor is positioned, an unconditional breakpoint is added. If a breakpoint exists on the source line where the cursor is positioned, it is removed.F9=Retrieve • Shows the last debug command you entered on the Debug command line, along with any parameters you included. Pressing this key once shows the last command you ran. Pressing the key twice shows the next-to-last command you ran, and so on.F10=Step Puts the program being displayed into step-over mode. After one statement of the program runs, the Display Module Source display is shown. To step through more than one statement, type in the step command with a value entered for the statement count parameter.F11=Display variable • Displays the current value of the variable on which the cursor is positioned. This function scans for the first character string matching the compiler language naming rules, which may or may not be an actual variable in the program, depending on where the cursor was placed. Once a character string matching the rules found, an EVAL command is issued for that string.F12=Resume • Stops the source debugger and returns to the previous menu or display. If a program is running, the program continues. Breakpoints set in the module remain set, and the session remains in debug mode. Breakpoints set in original program model (OPM) programs under source level debug remain set and the session is still in debug mode. Any watches set on variables in a program remain set to the storage addresses the variables occupied when the watches were set.F13=Work with module breakpoints • Shows the Work with Module Breakpoints display. The breakpoints in ILE modules, OPM programs, and Java class files being debugged are shown.F14=Work with module list • Shows the Work with Module List display.3-34 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty F15=Select view • Shows the Select View window. F16=Repeat find • Repeats the last FIND command entered. F17=Watch variable • Sets a watch on the variable on which the cursor is positioned. This function scans for the first character string matching the compiler language naming rules, which may or may not be an actual variable in the program, depending on where the cursor was placed. Once a character string matching the rules is found, a WATCH command is issued for that string. If this key is used when a Java class file is displayed, the watch will not be set because the watch is not supported for Java class files. F18=Work with watch • Shows the Work with Watch display. The watches for this job are shown. F19=Left • Shifts the window through which the source is being displayed left 12 characters. F20=Right • Shifts the window through which the source is being displayed right 12 characters. F21=Command line • Shows a command entry window. F22=Step into • Puts the program being displayed into step-into mode. After one statement of the program runs, the Display Module Source display is shown. To step through more than one statement, type in the step command with a value entered for the statement count parameter. F23=Display output • Shows the C/C++ application user output display, such as the output from a printf statement. F24=More keys • Displays additional function keys. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-35 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook IBM i: Debug commands (1 of 2) IBM i Command and Description Abbreviation ATTR Permits you to display the attributes of a variable attr BREAK Permits you to enter either an unconditional or conditional breakpoint br at a position in the program being tested CLEAR Permits you to remove conditional and unconditional breakpoints c DISPLAY Allows you to display the names and definitions assigned by using di the EQUATE command EQUATE Allows you to assign an expression, variable, or debug command to a eq name for shorthand use EVAL Allows you to display or change the value of a variable or to display ev the value of expressions STEP Allows you to run one or more statements of the program being s debugged FIND Searches the module currently displayed for a specified line number f or string or text UP Moves the displayed window of source towards the beginning of the u view by the amount entered DOWN Moves the displayed window of source towards the end of the view do by the amount entered © Copyright IBM Corporation 2010Figure 3-22. IBM i: Debug commands (1 of 2) OL209.0Notes:The following debug commands are only valid during program execution: • find • step • up • attr • break • clear • display • equate • eval3-36 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty IBM i: Debug commands (2 of 2) IBM i Command and Description Abbreviation LEFT Moves the displayed window of source to the left by the number of l characters entered RIGHT Moves the displayed window of source to the right the number of r characters entered TOP Positions the view to show the first line t BOTTOM Positions the view to show the last line bo NEXT Positions the view to the next breakpoint in the source currently n displayed PREVIOUS Positions the view to the previous breakpoint in the source currently p displayed HELP Shows the online help information for the available source debugger h commands WATCH Requests that the program stops when the contents of a variable w changes Set Specifies if case sensitive or case insensitive searching is performed se for all subsequent FIND requests. It also allows you to change the update production files value. © Copyright IBM Corporation 2010 Figure 3-23. IBM i: Debug commands (2 of 2) OL209.0 Notes: The following debug commands are only valid during program execution: • set • watch • left • right © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-37 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Client debug tools IBM i • Integrated debug – Part of RDi/RDP/RSE • Graphical interface – ILE or OPM languages – Use during i development • When you start debugger – Option of starting and debugging application – Option of debugging existing job on the i server • Debugger/servers are components of Rational Development Studio (5770-WDS) © Copyright IBM Corporation 2010Figure 3-24. Client debug tools OL209.0Notes:With a single user interface, you can debug CL (and other) programs from your WindowsPC.The i debug engine uses application program interface (API) calls to the system debuggerto obtain all necessary information.Your application still executes on the i host.3-38 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Integrated debug IBM i • The debugger client user interface allows you to: – View source code or compiler listings – Control program execution – Set, change, delete, enable, and disable line breakpoints – Set watch breakpoints to make your program stop when a variable changes – Step through code one line at a time – Display variables and their values – Display programs, service programs, and ILE modules • Same functions as STRDBG, but: – Multiple views in single window – Can see more – Easier to track program flow © Copyright IBM Corporation 2010 Figure 3-25. Integrated debug OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-39 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Starting the debug server IBM i • Can be started from RSE • On the i start the debug server (STRDBGSVR) Note: If the debug server is not started, an error message appears when you try to debug from your PC. • To debug interactive programs, you need a 5250 session. • TCP/IP must be configured on workstation and the i. © Copyright IBM Corporation 2010Figure 3-26. Starting the debug server OL209.0Notes:A message will indicate that the debug server is not started.To start the debug server from Remote Systems Explorer (RSE), locate the Objects iconunder the IBM i of choice and right-click Objects -> Remote Servers -> Debug -> Start.As an alternative, the STRDBGSVR command could be issued. Once started, the debugserver remains active until it is explicitly ended (ENDDBGSVR) or the IBM i is re-IPLed.The Debug perspective should open when debug of a program is requested.If the Remote Systems Explorer communications server has been shut down and needs tobe restarted, go to your 5250 emulator session and restart the Remote System Explorercommunications server by following the instructions in the message.3-40 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Start from RSE/LPEX editor: Interactive application IBM i © Copyright IBM Corporation 2010 Figure 3-27. Start from RSE/LPEX editor: Interactive application OL209.0 Notes: From the RSE/LPEX Editor view find the program from the listed libraries in your library list. Right-click it, then select the icon Debug (Service Entry)-> Set Source Entry Point. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-41 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook3-42 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 3.3. Additional testing facilities © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-43 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Additional testing facilities IBM i After completing this topic, you should be able to: • Describe the concepts of object, library and library list • Enter, create and execute a basic CL program, given the source statements for the program © Copyright IBM Corporation 2010Figure 3-28. Additional testing facilities OL209.0Notes:3-44 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Retrieve CL program source: RTVCLSRC IBM i QCLSRC No comments CL Program APL01XXX Prologue added APL01XXX All statements in keyword format CRTBDNCL ... ALWRTVSRC(*YES) CRTCLMOD ... CRTCLPGM ... RTVCLSRC PGM(APL01XXX) SRCFILE(QCLSRC) SRCMBR(APL01RTV) © Copyright IBM Corporation 2010 Figure 3-29. Retrieve CL program source: RTVCLSRC OL209.0 Notes: If a CL program is created with parameter ALWRTVSRC(*YES), the source can be retrieved. Source code line numbers are no longer equal to the compiled programs line numbers. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-45 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Example of source from RTVCLSRC IBM i 100 /********************************************************************************** / 200 /* * / 300 /* 5770SS1 VxRxMx yymmdd RTVCLSRC Output 07/20/10 12:15:26 * / 400 /* * / 500 /* Program name . . . . . . . . : APL01XXX PN* / 600 /* Library name . . . . . . . : OL20V9LIB PL* / 700 /* Original Source file . . . . . : QCLSRC SN* / 800 /* Library name . . . . . . . . : OL20V9LIB SL* / 900 /* Original source member . . . . : APL01XXX SM* / 1000 /* Source file change * / 1100 /* data/time . . . . . . . 06/05/09 09:42:25 SC* / 1200 /* Patch option . . . . . . . . : *NOPATCH PO* / 1300 /* User profile . . . . . . . . : *User UP* / 1400 /* Text . . . . . . . . . .Menu-like program lab sample soln. TX* / 1500 /* Owner . . . . . . . . . . : QSECOFR OW* / 1600 /* Patch change ID . . . . . . . : PC* / 1700 /* Patch APAR ID . . . . . . . : PA* / 1800 /* User mod flag . . . . . . . *Yes ED* / 1900 /* ED* / 2000 /********************************************************************************** / 2100 APL01XXX: + 2200 PGM 2300 DCLF FILE(APD01XXX) 2400 START: + 2500 SNDRCVF RCDFMT(MENUFMT) 2600 IF COND(&IN03) THEN(RETURN) 2700 ELSE CMD(IF COND(&OPTION = 1 ) THEN(DSPDTA DFUPGM(APD45))) 2800 ELSE CMD(IF COND(&OPTION = 2 ) THEN(CALL PGM(APR200))) 2900 ELSE CMD(IF COND(&OPTION = 3 ) THEN(RUNQRY QRY(APQ42))) 3000 ELSE CMD(IF COND(&OPTION = 90 ) THEN(SIGNOFF))) 3100 GOTO CMDLBL(START) 3200 ENDPGM © Copyright IBM Corporation 2010Figure 3-30. Example of source from RTVCLSRC OL209.0Notes:The prologue is useful if a new version of the program needs to be created due to changesin the commands it uses or if the original source is lost.Comments in the original source program are not retrieved.The commands are formatted in keyword format.A prologue is added to the new source member.3-46 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty A program dump is a valuable debugging tool IBM i 5770SS1 VnRnMn yymmdd CL Program Dump Job name . . . DSP02 User name . . .OL20001 Job number . . 014960 Program name . .APL01BUG Library . . . .OL20001 Statement . . . .1900 Messages Message Message Time ID Sev Type Text 132825 QRY1610 30 ESC Query APX42 not found In *LIBL. 132826 CPF9999 40 ESC Function check. QRY1610 unmonitored by APL01BUG at statement 700, Instruction XX. Variable Type Length Value Value in Hexadecimal *. . .+. . .1. . .+. . .2. . .+ *. . .+. . .1. &IN03 *CHAR 1 0 F0 &OPTION *CHAR 3 3 F34040 © Copyright IBM Corporation 2010 Figure 3-31. A program dump is a valuable debugging tool OL209.0 Notes: This figure shows a sample program dump. The beginning of the dump shows information about the job and the program. Following are the messages in the program message queue. This is where you look for error messages. The last section shows the programs variables, their type, length, and current value. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-47 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Requesting a program dump IBM i 100 CHECKCLP: PGM . . . 1700 ELSE IF (&TYPE=S) CHGVAR &GROS &SALARY 1800 ELSE RETURN 1900 DMPCLPGM 2000 CALL REGISTER (&GROSS &REG &OT) Planned 2100 ENDPGM Unplanned: "D" response when running a program Display Program Messages Job 204734/QSECOFR/DOUG started on mm/dd/yy at 09:58:42 in subsystem QINTER. QRY1610 received by APL01BUG at 700. (C D I R) Type reply, press Enter. Reply . . . D F3=Exit F12=Cancel View spool file QPPGMDMP. © Copyright IBM Corporation 2010Figure 3-32. Requesting a program dump OL209.0Notes:CL program dumps are easy to read. They can be a planned (DMPCLPGM command inthe program) or unplanned (D response to inquiry message CPA0701) debugging aid. Thedump shows all variables and the contents of the programs message queue.The command is included in the program for debugging. It should be removed once theprogram is debugged.3-48 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty STRISDB, STRSRVJOB, TRCJOB and STRTRC IBM i • STRISDB • STRSRVJOB • TRCJOB *ON/*OFF/*END • STRTRC, ENDTRC, PRTTRC and DLTTRC – No STRSRVJOB is required to trace other jobs – Can trace up to eight jobs with one STRTRC command – Can trace one generic job (limit of one generic trace system-wide) – Can trace generic job name with user name (QPADEV*/QUSER) – Can trace job name with no job number (QSCSRVR/QUSER) – Offers improved granularity in performance statistics © Copyright IBM Corporation 2010 Figure 3-33. STRISDB, STRSRVJOB, TRCJOB and STRTRC OL209.0 Notes: The Start Interactive Source Debugger Session (STRISDB) command puts a job into debug mode. The ENDISDB ends your interactive source debugger session for serviced jobs. The interactive source debugger is used to debug OPM RPG/400, COBOL, and CL in V3R1, V3R2, V3R6, and V3R7. You could find documentation in ADTS/400 Interactive Source Debugger, SC09-1897. This method is replaced by STRDBG for ILE. The Start Service Job (STRSRVJOB) command starts the remote service operation for a specified job (other than the job issuing the command) so that other service commands can be entered to service the specified job. Dump, debug, and trace commands can be run in that job until service operation ends. This command is often used to debug batch jobs. Service operation continues until the End Service Job (ENDSRVJOB) command is run. The Trace Job (TRCJOB) command, which functions with both OPM and ILE programs, controls traces of OPM programs and ILE procedure calls and returns that occur in the current job or in the job being serviced as a result of the Start Service Job (STRSRVJOB) command directed to that job. This command, which sets a trace on or off, can trace module flow, IBM i system data acquisition (including CL command traces), or both. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-49 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookAs the trace records are collected, they are stored in an internal trace storage area. Whenthe trace is ended, the trace records can be written to a spooled printer file, QPSRVTRC.The trace records can also be directed to a database output file.If the Start Service Job (STRSRVJOB) command is entered before the TRCJOBcommand, the job that is traced is the one identified by the STRSRVJOB command. Thetrace output from the serviced job is returned to the servicing job after the trace is set off orafter the serviced job has ended. Debugging a batch job can be a very delicate task.Specific steps have to be followed in sequence in order to use the Source Debug facilities:1. Submit job to run in batch with HOLD(*YES).2. Use WRKSBMJOB to obtain information about the job you want to debug, that is: • Job ID • User Name • Job Number3. Enter the command STRSRVJOB for the job above using the information that you retrieved using WRKSBMJOB.4. Enter the STRDBG command for the program that the batch job is running. The source view of the program is displayed.5. Press F21 to obtain a command line.6. Enter WRKSBMJOB from the command line to release the batch job; a system message will appear allowing you to press F10 to enter Debug commands or Enter to run the program.7. Press F10; a Command Entry screen appears.8. Use DSPMODSRC from the Command Entry display and set breakpoints where desired.9. Exit DSPMODSRC (F3).10. Exit the Command Entry screen (F12); the system message from Step 6 will appear again.11. Press Enter to run the program.12. Program now halts at breakpoint.13. Debug program as normal.When the program/job has completed execution, close out the process with ENDDBG andENDSRVJOB.The Start Trace (STRTRC) command starts traces of OPM programs, ILE procedures andJava (compiled and JIT). Tracing can be done for multiple jobs using this command. Anynumber of trace sessions can be started, but active trace session identifiers must beunique across the system. This command can trace call-return flow, data returned by tracepoints defined in the operating system, component trace information, or all three.3-50 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Display program references: DSPPGMREF IBM i Display spooled File File . . . . . : QPDSPPGM Control . . . . : __________ Find . . . . . : ________________________ *...+... 1...+... 2...+... 3...+... 4...+... 5...+... 6...+... 7...+... mm/dd/yy Display Program References DSPPGMREF Command Input Program . . . . . . . . . . . . . . . . . : PAY01 Library . . . . . . . . . . . . . . . : PAYLIB Output . . . . . . . . . . . . . . . . . : OUTPUT * Program . . . . . . . . . . . . . . . . . : PAY01 Library . . . . . . . . . . . . . . . : PAYLIB Text description . . . . . . . . . . : Number of objects referenced . . . . . : 2 Object . . . . . . . . . . . . . . . . . : PAYMAST Library . . . . . . . . . . . . . . . : *LIBL Object type . . . . . . . . . . . . . : *FILE Object . . . . . . . . . . . . . . . . . : TAXPGM Library . . . . . . . . . . . . . . . : *LIBL Object type . . . . . . . . . . . . . : *PGM More... F3=Exit F12=Cancel F19=Left F20=Right F24=More Keys © Copyright IBM Corporation 2010 Figure 3-34. Display program references: DSPPGMREF OL209.0 Notes: This display shows the first part of a sample Display Program References display. It shows the objects (*FILE, *DTAARA, *PGM) referenced by this program. Should these objects change, this command allows you to find the programs that may be affected by the change. You would output to a database file, then build a logical file over it to select the records concerning the object that changed. In this figure, you see that PAYMAST (*FILE) and TAXPGM (*PGM) are referenced by the PAY01 program. © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-51 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Print command usage: PRTCMDUSG IBM i 5770SS1 V7R1M0 100715 Print Command Usage Commands requested . . . . . . : *LIBL/CHGVAR Programs requested . . . . . . : OL20LIB/*ALL Command Use Detail Program Library Command Library Comma ADDBUGXXX OL20LIB CHGVAR *LIBL ADDNOBUG OL20LIB CHGVAR *LIBL ADDXXX OL20LIB CHGVAR *LIBL APL02XXX OL20LIB CHGVAR *LIBL APL91BXXX OL20LIB CHGVAR *LIBL APL91CXXX OL20LIB CHGVAR *LIBL CL programs using commands . . . . . . . . . : 39 CL programs searched . . . . . . . . . . . . : 69 * * * * * E N D O F C O M M A N D U S E © Copyright IBM Corporation 2010Figure 3-35. Print command usage: PRTCMDUSG OL209.0Notes:If anything about a command changes, you need to identify the programs that referencethis command to examine the effects of the change on the program. Use the PRTCMDUSGto find all the programs that use a particular command.In this example, the request that all programs in the library be searched for the CHGVARcommand is issued. This report is condensed for educational purposes. You see thatprograms ADDBUGXXX and ADDNOBUG (among others) use the command. A total of 69CL programs were searched, and 39 of them use the CHGVAR command.3-52 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint (1 of 2) IBM i 1. True or False: The CRTBNDCL command creates a single module, ILE control language program from the specified CLLE source code. 2. True or False: The parameter ALWRTVSRC, is available only on the CRTCLPGM command. 3. In order to get more detailed text for the error messages in your compile listing, you must specify ______ for the OPTION parameter of the CRTBNDCL command. © Copyright IBM Corporation 2010Figure 3-36. Checkpoint (1 of 2) OL209.0Notes:3-53 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint (2 of 2) IBM i 4. The EVAL command, entered on the debug command line, a. will display the value for the specified variable. b. will display the attributes, length and data type, of a variable. c. will ‘watch’ the value of a variable every time it changes. d. will do nothing if the declared variable is part of a declared file. 5. True or False: The IBM i integrated debugger has similar function to the 5250 debug tool. © Copyright IBM Corporation 2010 Figure 3-37. Checkpoint (2 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-54 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Workstation exercises IBM i • Lab 7A: Debugging with STRDBG (required) • Lab 7B: Debugging with Integrated Debug (optional) © Copyright IBM Corporation 2010Figure 3-38. Workstation exercises OL209.0Notes:3-55 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit summary IBM i Having completed this unit, you should be able to: • Describe how to create and call ILE modules, programs, and service programs • State the purpose of the parameters on the CRTBNDCL command • Use interactive source debugging facilities © Copyright IBM Corporation 2010 Figure 3-39. Unit summary OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 3. Program creation and debugging 3-56 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 4. Intermediate CL programming What this unit is about Using messages and the more advanced facilities of Control Language builds on the skills learned in basic CL programming. What you should be able to do After completing this unit, you should be able to: • Write CL programs using the following techniques: - Built-in functions (%SWITCH, %SST, %ADDRESS, %OFFSET, and %BINARY) - Data areas - External attributes - Date conversion - Command prompting - Messages (immediate, predefined) - Monitor message commands - System reply list • Write utility CL programs that process the output of display commands How you will check your progress • Machine exercises • Checkpoint questions © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit objectives IBM i After completing this unit, you should be able to: • Write CL programs using the following techniques: – Built-in functions (%SWITCH, %SST, %ADDRESS, %OFFSET, and %BINARY) – Data areas – External attributes – Date conversion – Command prompting – Messages (immediate, predefined) – Monitor message commands – System reply list • Write utility CL programs that process the output of display commands © Copyright IBM Corporation 2010Figure 4-1. Unit objectives OL209.0Notes:4-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 4.1. Additional control language programming © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Additional control language programming IBM i After completing this topic, you should be able to: • Use built-in functions – %SWITCH – %SST – %ADDRESS – %OFFSET – %BINARY • Use general and local data areas • Retrieve and alter external attributes • Convert date data • Command prompt during program execution © Copyright IBM Corporation 2010Figure 4-2. Additional control language programming OL209.0Notes:4-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Job switches and %SWITCH built-in function IBM i Job Switches Allows program-to-program Program 0 1 1 0 0 0 0 0 communication within a job Stack Temporary: Indicates job start/end QCMD Initially set by *JOBD: Default is PGMA 00000000 Use mask to test or check: 1=on, PGMB 0=off, X=ignore %SWITCH(mask) can be used as PGMC a logical variable 1. IF (%SWITCH(10XXXXX0)) CALL APL999 2. IF (&BAL > 0) CHGJOB SWS(1XXXXXXX) 3. CHGVAR &IN90 %SWITCH(00000001) © Copyright IBM Corporation 2010 Figure 4-3. Job switches and %SWITCH built-in function OL209.0 Notes: The switch built-in function (%SWITCH) compares a switch setting mask against the eight job switches. If every switch compared is the same, a logical value of 1 (true) is assigned to the expression. Otherwise, a value of 0 (false) is assigned to the expression. Job switches provide program-to-program communication within a job. The switches are initially set by the job description and are changed by the SBMJOB, CHGJOB, or JOB commands. Other high-level language (HLL) programs may also use the job switches. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Extracting part of a *CHAR value IBM i %SUBSTRING OR %SST %SST ( *LDA variable-name X Y ) 1 2 3 X Y Example: Extract team number from user name. &USER CLP007 CHGVAR VAR(&TEAM) VALUE(%SST(&USER 4 3)) &TEAM 007 © Copyright IBM Corporation 2010Figure 4-4. Extracting part of a *CHAR value OL209.0Notes:X = Starting position. A variable may be used.Y = Length. A variable may be used.The above example shows how a portion of a string can be extracted from a charactervariable. The %SST function is coded as part of the VALUE keyword on the CHGVARcommand.4-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Example: Creating class profiles IBM i PGM PARM(&TEAMSA) DCL VAR(&COUNT) TYPE(*INT) LEN(4) DCL VAR(&COUNTA) TYPE(*CHAR) LEN(3) DCL VAR(&TEAMS) TYPE(*INT) LEN(4) DCL VAR(&TEAMSA) TYPE(*CHAR) LEN(3) DCL VAR(&USER) TYPE(*CHAR) LEN(6) + VALUE(CLPXXX) CHGVAR VAR(&TEAMS) VALUE(&TEAMSA) DOFOR VAR(&COUNT) FROM(1) TO(&TEAMS) CHGVAR VAR(&COUNTA) VALUE(&COUNT) CHGVAR VAR(%SST(&USER 4 3)) VALUE(&COUNTA) CRTUSRPRF USRPRF(&USER) ENDDO © Copyright IBM Corporation 2010 Figure 4-5. Example: Creating class profiles OL209.0 Notes: &TEAMSA is passed to this program by another program (not shown) in the class setup process. The visual is not a complete program example. It is meant to show how %SST might be used. Note that the %SST function is used in the VAR keyword of the CHGVAR command. In other words, a string is being inserted into the variable &USER. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook %SUBSTRING example: Saving libraries IBM i Using Variable for Position : Call SAVPGM PARM(ABCDEFGHIJK TAP01) PGM PARM(&STREAM &TAPE) /*SAVES LIBRARIES */ DCL VAR(&STREAM) TYPE(*CHAR) LEN(32) DCL VAR(&TAPE) TYPE(*CHAR) LEN(10) DCL VAR(&LIB) TYPE(*CHAR) LEN(6) VALUE(IWLIBX) DCL VAR(&X) TYPE(*DEC) LEN(2 0) VALUE(1) DOWHILE 1 /* DO FOREVER */ CHGVAR VAR(%SUBSTRING(&LIB 6 1)) + VALUE(%SUBSTRING(&STREAM &X 1)) IF COND(&LIB =IWLIB ) THEN(LEAVE) SAVLIB LIB(&LIB) DEV(&TAPE) CHGVAR VAR(&X) VALUE(&X +1) /* Counter */ ENDDO ENDPGM © Copyright IBM Corporation 2010Figure 4-6. %SUBSTRING example: Saving libraries OL209.0Notes:This program saves a group of libraries with names from IWLIBA to IWLIBL.4-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Declare CL variable revisited IBM i DCL TYPE( ) STG( ) BASPTR ) DEFVAR( ) ADDRESS( ) TYPE( ) STG( ) BASPTR( ) DEFVAR( ) ADDRESS *AUTO (default) *DEFINED &DEFVAR *PTR *BASED &PTRVAR *PTR *AUTO &ADDRVAR © Copyright IBM Corporation 2010 Figure 4-7. Declare CL variable revisited OL209.0 Notes: The DCL command can be used to declare more than the traditional (*DEC, *CHAR, *LGL, *INT, and *UINT) data types in CL programs. We must take a closer look at some of the optional parameters of the DCL command. The storage (STG) parameter specifies the type of storage requested for the variable. Your choices are: • *AUTO - The storage for this variable is allocated in automatic storage. This is the default and is typically used for traditional variable definition. • *BASED - The storage for this variable is based on the pointer variable specified on the Basing pointer variable (BASPTR) parameter. A based CL variable cannot be used unless the basing pointer variable has been set to a valid address. We’ll look at some examples of how pointer variables are used and set to a valid address. • *DEFINED © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook - The storage for this variable is provided by the CL variable specified on the Defined on variable (DEFVAR) parameter. This parameter names and designates the starting position of the defined-on variable. If the starting position is not specified, the variable being declared will start at the beginning of the defined-on variable.The base pointer (BASPTR) parameter specifies the name of a CL variable declared asTYPE(*PTR) which will serve as the basing pointer for the based CL variable beingdeclared. This pointer must be initialized to a value before the based variable can be used.The defined on (DEFVAR) parameter specifies the CL variable that the variable beingdeclared is to be defined on.The address (ADDRESS) parameter specifies the initial address for a CL variable declaredwith *PTR as the TYPE value.4-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Defined variables IBM i DCL &OBJECT *CHAR 20 DCL &OBJNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT) DCL &LIBNAME *CHAR 10 STG(*DEFINED) DEFVAR(&OBJECT 11) MYOB J EC T MY L I B RAR Y 1 2 3 4 5 6 7 8 9 10 . . . . . . . . . . . . . .. 20 &OBJNAME MYOBJECT &LIBNAME MYLIBRARY © Copyright IBM Corporation 2010 Figure 4-8. Defined variables OL209.0 Notes: 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. You can map different parts of the defined-on variable or the same part of a given variable in different ways. In the above example, the variable &OBJNAME is equal to the first 10 bytes of &OBJECT and the variable &LIBNAME is equal to the last 10 bytes of &OBJECT. Using the defined variables &OBJNAME and &LIBNAME improves the readability of the code and makes it easier to work with. The variable &OBJECT provides the storage for both the &LIBNAME and &OBJNAME variables. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Pointer, defined and based variables examples IBM i • Examples: –(1) DCL &CHAR *CHAR LEN(10) DCL &PTR *PTR ADDRESS(&CHAR) –(2) DCL &PTR *PTR DCL &CHAR *CHAR LEN(10) STG(*BASED) BASPTR(&PTR) –(3) DCL &PAYREC *PTR STG(*AUTO) ADDRESS(*NULL) –(4) DCL &CHAR *CHAR LEN(48) DCL &PTR *PTR STG(*DEFINED) DEFVAR(&CHAR 17) © Copyright IBM Corporation 2010Figure 4-9. Pointer, defined and based variables examples OL209.0Notes:The examples in this visual show how to use pointer, defined and based variables. In the first example, the second DCL command declares a pointer variable which isinitialized to point to the &CHAR variable in the programs automatic storage.In the second example, the second DCL command declares a character variable which isfound at the location addressed by the &PTR variable. Before the &CHAR variable can beused, the &PTR variable must be initialized to a valid address by using the %ADDRESSbuilt-in function.In the third example, the pointer variable &PAYREC is declared with an initial addressvalue of null.In the fourth example, the second DCL command declares a pointer variable in bytes 17through 32 of the variable &CHAR.4-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Local data area, *LDA IBM i Data type *CHAR Length 1024 Sign-on: Start of job DSP02 RA AA ... *LDA set to blank G DT CH or RA *LDA for DSP02 QCMD AR AA SBMJOB TIME GV DT COPIED AT CH V RT or PGMA V AR G CH PGMB SBMJOB... JOB: BATCH01 SIGN-OFF *LDA for BATCH01 *LDA-deleted Also DSPDTAARA © Copyright IBM Corporation 2010 Figure 4-16. Local data area, *LDA OL209.0 Notes: Local data area (*LDA) is supported by CL, COBOL, and RPG. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Accessing local data area IBM i PROGA PGM CHGVAR VAR(%SST(*LDA 6 10)) VALUE(MYFILE) or CHGDTAARA DTAARA(*LDA (6 10)) VALUE(MYFILE) CALL PGMB *LDA ______________MYFILEbbbb 1 6 PROGB PGM DCL VAR(&FILE) TYPE(*CHAR) LEN(10) CHGVAR VAR(&FILE) VALUE(%SST(*LDA 6 10)) or RTVDTAARA DTAARA(*LDA (6 10)) RTNVAR(&FILE) © Copyright IBM Corporation 2010Figure 4-17. Accessing local data area OL209.0Notes:The group data area (*GDA) works similarly. A substring-like function can be used toaccess the local data area. Commands for either data areas or variables can be used.4-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Data area objects (*DTAARA) IBM i Next sequential number: Invoices, checks and so forth Names: International Business Machines Corporation Better than a *FILE for storing small amount of information Job: DSP08 Job: DSP04 *DTAARA CHGDTAARA RTVDTAARA *CHAR CRTDTAARA DTAARA(name) TYPE *DEC LEN( ) VALUE( ) *LGL CHGDTAARA DTAARA(name (start length)) VALUE( ) RTVDTAARA DTAARA(name (start length)) RTNVAR(CL variable) Also WRKDTAARA, DSPDTAARA, DLTDTAARA © Copyright IBM Corporation 2010 Figure 4-18. Data area objects (*DTAARA) OL209.0 Notes: A data area (created by CRTDTAARA) is an object used to hold data for access by any job on the system. The data is only one physical field, although character data areas may logically be several pieces of information. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Data area programming example IBM i CRTDTAARA DTAARA( CHECKNO ) TYPE( *DEC ) LEN( 5 0 ) VALUE( 1 ) PGM DCLF PAYOUT DCL &CHK#FLD *DEC (5 0) Enter name and amount: Pay to the order of SNDRCVF RCDFMT(CHKENT) _______________ Amount________ ALCOBJ OBJ((CHECKNO *DTAARA *EXCL)) RTVDTAARA CHECKNO RTNVAR( &CHK#FLD) CHGVAR &CHK#FLD ( &CHK#FLD + 1 ) DTAARA: CHECKNO 00001 CHGDTAARA CHECKNO ( &CHK#FLD ) DLCOBJ OBJ((CHECKNO *DTAARA *EXCL )) CALL CHECKWRITE (&NAME &AMT &CHK#FLD) ENDPGM © Copyright IBM Corporation 2010Figure 4-19. Data area programming example OL209.0Notes:In this example, a data area is used to hold the current check number, which can beaccessed by multiple users. The Allocate Object (ALCOBJ) command is used to obtain alock state on an object for the current job so that no other job can use it at the same time.A data area called CHECKNO is created with an initial value of one. The program takes thefollowing steps: • The program declares a display file and declares a field (&CHK#FLD) to hold the value of the data area CFHECKNO. • The program displays a format which allows the entry of name and amount. • The program reads the format. • The program allocates the data area exclusively with the ALCOBJ command to ensure that no other job accesses the data area while this job is reading and updating it. • The program retrieves the data area into field &CHK#FLD and adds one to the value. • It uses the new value to replace the contents of the CHECKNO data area. • The program deallocates the data area so that other jobs may access it. • The program calls program CHECKWRITE and passes field &CHK#FLD, which contains the value of the data area as it existed when this program first accessed it.4-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Retrieving external attributes IBM i JOB JOB JOB JOB SYSTEM USER GROUP ATTRIBUTES VALUES PROFILE ATTRIBUTES RTVJOBA RTVSYSVAL RTVUSRPRF RTVGRPA CHGJOB CHGSYSVAL CHGUSRPRF CHGGRPA CHGPRF *LIN *CTL *DEV Configuration Network OBJECT MEMBER Status Attributes DESCRIPTION DESCRIPTION RTVNETA RTVOBJD RTVMBRD RTVCFGSTS CHGNETA CHGJOB CHGJOB © Copyright IBM Corporation 2010 Figure 4-20. Retrieving external attributes OL209.0 Notes: Information external to a program can be retrieved into CL program variables for use in the program. Likewise, a CL program can reach out and change these values. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Example: Using RTVJOBA to make a general initial program IBM i PGM DCL VAR(&USER) TYPE(*CHAR) LEN(10) RTVJOBA USER(&USER) CHGCURLIB CURLIB(&USER ) CHGJOB OUTQ(&USER) PRTTXT(OUTPUT FOR *BCAT &USER) + LOG(4 00 *SECLVL) LOGCLPGM(*YES) STRPDM ENDPGM © Copyright IBM Corporation 2010Figure 4-21. Example: Using RTVJOBA to make a general initial program OL209.0Notes:4-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty RTVJOBA and CHGJOB example IBM i Temporarily changes jobs default *OUTQ. Sends message to the user who is running the program. PGM DCL VAR(&OUTQNAME) TYPE(*CHAR) LEN(10) DCL VAR(&OUTQLIB) TYPE(*CHAR) LEN(10) RTVJOBA OUTQ(&OUTQNAME) OUTQLIB(&OUTQLIB) CHGJOB OUTQ(PAYLIB/PAYOUTQ) CALL PGM(PAYCHECKS) CHGJOB OUTQ(&OUTQLIB/&OUTQNAME) SNDMSG MSG(Checks sent to PAYOUTQ output queue.) + TOUSR(*REQUESTER) ENDPGM © Copyright IBM Corporation 2010 Figure 4-22. RTVJOBA and CHGJOB example OL209.0 Notes: This example shows how external attributes can be used to send a report to a special output queue, then set the default output queue for the job back to its previous value. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Convert date command IBM i CVTDAT DATE(Constant or Variable) TOVAR(CL Variable)FROMFMT *JOB TOFMT *JOB TOSEP *JOB *SYSVAL *SYSVAL *SYSVAL *MDY *MDY *NONE *MDYY *MDYY Separator CHAR *DMY *DMY *DMYY *DMYY *YMD *YMD *YYMD *YYMD *CYMD *CYMD *JUL *JUL *ISO *ISO *USA *USA *EUR *EUR *JIS *JIS *LONGJUL *LONGJUL © Copyright IBM Corporation 2010Figure 4-23. Convert date command OL209.0Notes:In many applications, you may want to use the current date in your program by retrievingthe system value QDATE or job date and placing it in a variable. You may also want tochange the format of that date for use in a program. To convert the format of a date in a CLprogram, use the convert date (CVTDAT) command.The format of the date is the system value QDATFMT, which is initially MDY. The dateformat can be changed to the YMD, DMY or the JUL (Julian) format. You can also eliminatedate separators or change the character used as a date separator with this command.Formats with one Y have two-digit dates and formats with YY have four-digit dates. Makesure the variable used in the TOVAR parameter is long enough to hold all the date digitsand separator characters, if present. If either the from-format or the to-format uses only twodigits to specify the year, valid dates are in the range of January 1, 1940, to December 31,2039. Otherwise, valid dates are in the range of August 24, 1928, to May 9, 2071. If theyear is specified with only two digits, years in the range of 40 to 99 are assumed to be 1940to 1999; years in the range 00 to 39 are assumed to be 2000 to 2039. The command worksin conjunction with the QLEAPADJ system value.4-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebooky Other formats: • *CYMD: cyymmdd, where c is 0 for years 1928 through 1999, and is 1 for years 2000 through 2071. • *JUL: yyddd • *LONGJUL: yyyyddd • *ISO: yyyy-mm-dd (10 spaces) • *EUR: mm/dd/yyyy (10 spaces) • *JIS: yyyy-mm-dd (10 spaces) • *SYSVAL: Format specified by QDATFMT, which defaults to mmddyy © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-21 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook CVTDAT example IBM i Separate File Member for Each Days Transactions PGM DCL &MBR *CHAR LEN(10) DCL &SYSDATE *CHAR LEN(6) DCL &JUL *CHAR LEN(5) RTVSYSVAL QDATE RTNVAR(&SYSDATE) TRAN CVTDAT DATE(&SYSDATE) FROMFMT(*SYSVAL) + *FILE TOVAR(&JUL) TOFMT(*JUL) + TOSEP(*NONE) MEMBER TRAN92048 CHGVAR VAR(&MBR) VALUE(TRAN *CAT &JUL) MEMBER ADDPFM FILE(TRAN) MBR(&MBR) TRAN92049 OVRDBF FILE(TRAN) MBR(&MBR) CALL PGM(PAYTRAN) ENDPGM © Copyright IBM Corporation 2010Figure 4-24. CVTDAT example OL209.0Notes:This program allows an application to add and use a new physical file member to atransaction file for each days transactions.4-22 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using the prompter within a CL procedure or program IBM i No ? precedes command. Some parameters specified with prefixes: Parameter Specified in Program Displayed? Status ??KEYWORD( ) or ??KEYWORD(value) Yes Unprotected ?*KEYWORD() or ?*KEYWORD(value) Yes Protected KEYWORD(value) No Not specified No ? Precedes command. Show all parameters. Parameter Specified in Program Displayed? Status ??KEYWORD( ) or ??KEYWORD(value) Yes Unprotected ?*KEYWORD() or ?*KEYWORD(value) Yes Protected KEYWORD(value) Yes Protected Not specified Yes Unprotected ?-KEYWORD() or ?-KEYWORD(value) Exception: No © Copyright IBM Corporation 2010 Figure 4-25. Using the prompter within a CL procedure or program OL209.0 Notes: If no value is specified, such as in the case of ??KEYWORD(), the default is used. The CL Programming manual describes the various prompting characters as follows: • ?? The parameter is displayed and input-capable. • ?* The parameter is displayed but is not input-capable. Any user-specified value is passed to the command processing program. • ?< The parameter is displayed and is input-capable, but the command default is sent to the command processing program (CPP) unless the value displayed on the parameter is changed. • ?/ The parameter is reserved for IBM use. • ?– The parameter is not displayed. The specified value (or default) is passed to the CPP. Not allowed in prompt override programs. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-23 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • ?& The parameter is not displayed until F9=All parameters is pressed. Once displayed, it is input-capable. The command default is sent to the CPP unless the value displayed on the parameter is changed. • ?% The parameter is not displayed until F9=All parameters is pressed. Once displayed, it is not input-capable. The command default is sent to the CPP.4-24 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Example: ?SNDMSG IBM i Send Message (SNDMSG) Type choices, press Enter. Message text . . . . . . . . . . MSG _______________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ To user profile. . . . . . . . .TOUSR _________ Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 4-26. Example: ?SNDMSG OL209.0 Notes: A question mark preceding a command is equivalent to typing the command and pressing F4=Prompt. F10 will display the additional parameters. Any command that is prompted at execution time should be followed by a MONMSG to handle the situation in which the user presses F3 or F12. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-25 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Example: ?SNDMSG TOMSGQ(QSYSOPR) IBM i Send Message (SNDMSG) Type choices, press Enter. Message text . . . . . . . . . . MSG _______________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _To user profile. . . . . . . . .TOUSR _________ Additional Parameters Protected To message queue. . . . . . . . TOMSGQ >QSYSOPR Library . . . . . . . . . . . *LIBL Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-27. ?SNDMSG TOMSGQ(QSYSOPR) OL209.0Notes:F10 displays the additional parameters. Continuing the previous example, if a parameter iscoded, it appears on the prompt screen, but it is protected. (Notice that QSYSOPR is notunderlined.)4-26 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Parameter prefix summary IBM i Value Passed to CPP if Value Nothing Displayed Protected Specified Highlighted You Enter ??KEYWORD( ) Default No Default No ??KEYWORD(VALUE) Value No Value Yes ?*KEYWORD( ) Default Yes Default No ?*KEYWORD(VALUE) Value Yes Value Yes ?-KEYWORD( ) None N/A Default N/A ?-KEYWORD(VALUE) None N/A Value N/A ?COMMAND ... ?- KEYWORD( ) { Required © Copyright IBM Corporation 2010 Figure 4-28. Parameter prefix summary OL209.0 Notes: If a keyword is preceded by “?-”, the command must be preceded by “?”. This chart gives more detailed information on the effect of certain parameter prefixes. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-27 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Example: ?SNDMSG ?-TOUSR(*SYSOPR) IBM i Send Message (SNDMSG) Type choices, press Enter. Message text . . . . . . . . . . MSG _______________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _____________________________________________________________ _ Parameter TOUSR is not displayed Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-29. Example: ?SNDMSG ?-TOUSR(*SYSOPR) OL209.0Notes:TOUSR is not one of the additional parameters and does not appear if F10 is pressed.Compare this visual to the previous visual, in which the following was coded: ?SNDMSG.The prefixes are best added after coding with the prompter, which means you will have tomodify every parameter that needs a prefix, even if you intend to use the default value (atleast one character needs to be over-typed) to set on the modified data tag (MDT).4-28 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Example: SAVLIB ??LIB(APLIB) ?*DEV(TAP01) ENDOPT(*UNLOAD) (1 of 2) IBM i Save Library (SAVLIB) Type choices, press Enter. Library . . . . . . . . . . .LIB >APLIB + for more values __________ Device. . . . . . . . . . . DEV >TAP01 Protected ENDOPT is not displayed No F10=Additional parameters Bottom F3=Exit F4=Prompt F5=Refresh F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 4-30. Example: SAVLIB ??LIB(APLIB) ?*DEV(TAP01) EBDOPT(*UNLOAD) (1 of 2) OL209.0 Notes: A parameter is not displayed unless it has an appropriate prefix. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-29 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Example: ?SAVLIB ??LIB(APLIB) ?*DEV(TAP01) ENDOPT(*UNLOAD) (2 of 2) IBM i Save Library (SAVLIB) Type choices, press Enter. Library . . . . . . . . . . .LIB >APLIB + for more values __________ Device. . . . . . . . . . . DEV >TAP01 Protected Volume identifier . . . . . VOL *MOUNTED + for more values _______________________ Sequence number . . . . . . SEQNBR *END Label . . . . . . . . . . . LABEL *LIB File expiration date. . . . EXPDATE *PERM Displayed, End of tape option. . . . . ENDOPT > *UNLOAD Use optimum block . . . . . USEOPTBLK *YES Protected Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-31. Example: ?SAVLIB ??LIB(APLIB) ?*DEV(TAP01) ENDOPT(*UNLOAD) (2 of 2) OL209.0Notes:The question mark preceding the command causes parameters to be prompted. Individualparameter prefixes can further control the prompting.4-30 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Workstation exercises IBM i • Lab 8: Data area retrieval (recommended) • Lab 9: External attributes (recommended) © Copyright IBM Corporation 2010 Figure 4-32. Workstation exercises OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-31 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook4-32 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 4.2. Defining messages © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-33 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Defining messages IBM i After completing this topic, you should be able to: • Understand the different types of messages • Use predefined messages • Use immediate messages • Work with message files © Copyright IBM Corporation 2010Figure 4-33. Defining messages OL209.0Notes:4-34 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Messages are always sent to message queues: Types of message queues IBM i CRTDEVDSP: CRTUSRPRF: Program DAVIS Message DSP01 Display *DEVD *USRPRF Workstation User Message Message Interactive Queue Queue External *EXT Message H DSP01 DAVIS Queue TC *MSGQ BA *MSGQ QCMD Job Message SNDxxxMSG Program Queue PGMA Message Queues ARDEPT QSYSOPR *MSGQ *MSGQ PGMB CRTMSGQ: System Supplied: QSYSOPR User Message System Operator Queue Message Queue © Copyright IBM Corporation 2010 Figure 4-34. Messages are always sent to message queues: Type of message queues OL209.0 Notes: This figure illustrates the basic message queues involved in communication on the i. When a device description is created, either by a command or automatically configured by the system, a workstation message queue with the same name is also created. When a user profile is created, a message queue with the same name is also created. Additionally, user message queues may be created with the Create Message Queue (CRTMSGQ) command. Some message queues, such as the system operator message queue (QSYOPR), are supplied by IBM. When messages are sent, they are always sent to message queues. A job message queue, a temporary structure for the duration of the job, is created at job initiation. The external (*EXT) part of the queue is used for programs within the job to communicate through messages with the user. When a program is initiated, a program message queue is added to the job message queue. Program message queues are used for program-to-program communication among programs in a jobs program stack. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-35 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Message communication within a job: Sending IBM i Program Stack TOMSGQ(*EXT) QCMD TOPGMQ(*EXT) External *EXT Message Queue QCMD PGMA Job TOPGMQ(*SAME PGMA) PGMA Message PGMB Program Queue Message TOPGMQ(*PRV *) PGMB Queues PGMC SNDUSRMSG Messages PGMC SNDPGMMSG From the System Sender determines message type © Copyright IBM Corporation 2010Figure 4-35. Message communication within a job: Sending OL209.0Notes: • Control returns to sending program for message types *INQ, *COMP, *DIAG, *RPY, and *RQS. • The job message queue allows communication among the user, the programs, and the system. • The system uses the job message queue to inform the user and the program of the results of a command or program. • Job and program message queues are created automatically and deleted automatically as jobs and programs begin and end.4-36 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Job message queue *EXT (1 of 2) IBM i CRTOUTQ OUTQ( JOBLOG ) JOB: DSP01 CHGPRTF FILE( QPJOBLOG ) OUTQ( JOBLOG ) *FILE: QPJOBLOG *EXT F I OUTQ(*JOB) PROG1 EOJ *OUTQ: JOBLOG L PROG2 T Operational E Assistant: PROG3 R OUTQ( QEZJOBLOG ) *OUTQ: QUSRSYS/QEZJOBLOG FILTER DSPJOBLOG © Copyright IBM Corporation 2010 Figure 4-36. Job message queue *EXT (1 of 2) OL209.0 Notes: The job log contains information related to requests entered for a job. It can be displayed while the job is still active and it can be written to the spooled file QPJOBLOG at the end of the job so that it can be printed. Whether a job log is printed and the level of detail printed is controlled by the LOG attribute of the job and the LOG parameter of the SIGNOFF command (interactive jobs). The LOG parameter of the SIGNOFF command takes precedence over the LOG attribute of the job. *FILE QPJOBLOG is shipped with OUTQ(*JOB), but as soon as operational assist is used (clean up is performed), the value is changed to OUTQ(QEZJOBLOG). © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-37 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Job message queue *EXT (2 of 2) IBM i Filter CRTCLPGM...LOG(*JOB/YES/*NO) commands CHGJOB message message message within CL programs CHGJOBD LOG level severity text . . . LOGCLPGM(*YES/NO) CRTJOBD level message-level message-severity message-text-level 0 - No data is logged *NOLIST: No log unless 1 - *EXT messages if severity *GE 0-99 abnormal EOJ 2 - Level 1 Commands and their messages if or SIGNOFF LOG(*LIST), severity *GE 0-99 then Message + Help text 3 - Level 1 *MSG: Message text Commands *SECLVL: Message + Help text Messages from commands if severity *GE 0-99 4 - Commands All messages if severity *GE 0-99 View job log online: QCMD display, F10, Roll Back © Copyright IBM Corporation 2010Figure 4-37. Job message queue *EXT (2 of 2) OL209.0Notes:It is much better to actually print the job log or history log to a spooled file that is not printedbecause it is much easier to scan for a character string using the spooled file display.To view the job log online, for the current job, go to the Command Entry display, chooseF10=Include detailed messages, and use the roll or page keys.4-38 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Which message types can be sent to which types of queues IBM i Message Queue Type Message Type External Program QSYSOPR Workstation User Informational V V V V V Inquiry V V V V Completion V V V V V Diagnostic V V V V V Request V V Escape V Status V V Notify V V V = Valid © Copyright IBM Corporation 2010 Figure 4-38. Which message types can be sent to which types of queues OL209.0 Notes: The IBM i program divides messages into types according to their use. These message types are categories based on the messages purpose. The sender of the message determines its type when sending the message. The message handling APIs use these message types in defining and working with messages: • Completion (*COMP): Reports the successful completion of a task. • Diagnostic (*DIAG): Describes errors in processes or input data. When an error occurs, a program usually sends an escape message, which causes the task to end abnormally. One or more diagnostic messages can be sent before the escape message to describe the error. • Escape (*ESCAPE): Indicates a condition causing a program to end abnormally, without completing its work. • Exception (*EXCP): Indicates a condition causing a program to end abnormally, without completing its work. An exception message can be either an escape or a notify © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-39 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook message. The exception message type and the special value *EXCP are used only with the Receive Program Message (QMHRCVPM) API. • Informational (*INFO): Conveys information without asking for a reply. • Inquiry (*INQ): Conveys information and asks for a reply. • Notify (*NOTIFY): Describes a condition in the sending program requiring corrective action or a reply. • Reply (*RPY): Responds to an inquiry or notify message. • Request (*RQS): Requests a function from the receiving program. • Senders copy (*COPY): Is a copy of an inquiry or notify message. This copy is kept by the sender of the inquiry or notify message. • Scope (*SCOPE): Specifies a program to run when the program this message is sent to completes. If the message is sent to *EXT the program is to run when the job completes. • Status (*STATUS): Describes the status of work being done by a program.4-40 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Immediate and predefined message IBM i Immediate: Composed in MSG parameter Predefined: Stored in a message file. SNDUSRMSG MSG(message-text) SNDPGMMSG SNDMSG Immediate SNDBRKMSG SNDUSRMSG MSGID(message-identifier) SNDPGMMSG Predefined © Copyright IBM Corporation 2010 Figure 4-39. Immediate and predefined message OL209.0 Notes: Immediate messages are composed within the command and can be used on all message commands (except when the message type is *ESCAPE). Predefined messages are used in programming to ensure consistency. Predefined messages have features not available for immediate messages, as shown in the following pages. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-41 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Predefined messages IBM i Create a message file. CRTMSGF MSGF(APMSGF) SIZE( ) AUT( ) TEXT( ) Create and maintain messages. *MSGF: APMSGF ADDMSGD CHGMSGD or WRKMSGD UAP0001 DSPMSGD UAP0002 RMVMSGD UAP0003 © Copyright IBM Corporation 2010Figure 4-40. Predefined messages OL209.0Notes:Message file QCPFMSG in library QSYS contains the system messages. Many programshave their own message files. For instance, RPG uses message files QRPGMSG andQRPGLEMSG. COBOL uses message files QCBLMSG, QCSCMSG and QLNCMSG,among others.4-42 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Work with Message Files IBM i WRKMSGF MSGF(CLPLAB/*ALL) Work with Message Files Type options, press Enter. 1=Create 2=Change 4=Delete 5=Display message descriptions 12=Work with message descriptions 13=Change description Message Opt File Library Text ___ __________ __________ 12 APMSGFXXX OL20LIB Message Programming Lab. Sample Student *MSGF ___ CLPLAB OL20LIB Message file for XLAB crossover training ___ CLPMSGF OL20LIB Message file for Setup/drop programs ___ COURSE OL20LIB ___ COURSELIB OL20LIB ___ CRTALL OL20LIB ___ XXXMSGF OL20LIB S/3X for the experienced S/38 implementer Bottom Parameters for options 1, 2, 5, 12 and 13 or command ==> _____________________________________________________________________ F3=Exit F4=Prompt F5=Refresh F9=Retrieve F11=Display names only F12=Cancel F16=Repeat position to F17=Position to © Copyright IBM Corporation 2010 Figure 4-41. Work with Message Files OL209.0 Notes: WRKMSGF can display a list of message files. Option 12 runs the WRKMSGD command. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-43 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Option 12: Work with message descriptions (WRKMSGD) IBM i Work with Message Descriptions System: DIRTCITY Message file: APMSGFXXX Library: OL20LIB Position to . . . . . ________________ Message ID Type options, press Enter. 2=Change 4=Delete 5=Display details 6=Print Opt Message ID Severity Message Text _ CPA0701 99 &3 received by &1 at &4. (C D I R) _ UAP0001 0 Cash requirements processing completed. _ UAP0002 0 Cash requirements listing must be given to AP super _ UAP0003 0 Discount totaling &1 are available. _ UAP0007 0 &1 records processed in file &2 Bottom Parameters or Command ===> __________________________________________________________________ F3=Exit F5=Refresh F6=Add F12=Cancel F24=More keys © Copyright IBM Corporation 2010Figure 4-42. Option 12: Work with message descriptions (WRKMSGD) OL209.0Notes:F6=Add runs the ADDMSGD command.4-44 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty F6=Add (ADDMSGD) (1 of 4) IBM i Add Message Description (ADDMSGD) Type choice, press Enter. Message identifier . . . . . . . . MSGID >UAP0004 Message file . . . . . . . . . . . MSGF >APMSGF Library . . . . . . . . . . . > OL20LIB First-level message text. . . . . MSG >&1 records processed in file &2. Second-level message text . . . SECLVL > If &1 records is incorrect, run APLEDIT. . . . ... Severity code . . . . . . . . . . . SEV 00 More . . . F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12-Cancel F13=How to use this display F24=More Keys © Copyright IBM Corporation 2010 Figure 4-43. F6=Add (ADDMSGD) (1 of 4) OL209.0 Notes: Message identifier (MSGID) Specifies the message identifier under which the message is stored in the message file. Every message must have an identifier, and every identifier in the message file must be unique. This is a required parameter. The message identifier must be seven characters in length and in the format pppnnnn The first three characters (ppp) must be a code consisting of an alphabetic character followed by two alphanumeric (alphabetic or decimal) characters. Examples include CPF, MCH, and SQ3. The last four characters must consist of numbers ranging from 0 through 9 and characters ranging from A through F. Examples include CPF4131 and CPF4AB7. First-level message text (MSG) Specifies the text of the message being defined. This text is the message that is initially shown, printed or sent to a program or log. A maximum of 132 characters enclosed in apostrophes can be specified, but the limitations of the display stations (their screen size) © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-45 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebookshould be considered. The entire message must be enclosed in apostrophes if blanks areincluded in the message. To code an apostrophe for use in the message, enter a doubleapostrophe.Second-level message text (SECLVL)(To expand the size of a parameter field, type an ampersand, followed by a blank (“&”), andthen press Enter. It is likely that this would be needed for parameter SECLVL.)Specifies the message help that is shown to a display station user to further explain themessage specified on the First-level message text prompt (MSG parameter). The userpresses the Help key to request the message help. Message help can also be written to thejob log if *SECLVL is specified on the Log in service log prompt (LOG parameter) of the jobcommands.Possible values are: • *NONE - There is no message help for this message description. • second-level-text - Specifies the message help that is shown when it is requested by the user. No more than 3000 characters enclosed in apostrophes can be specified, but display limitations must be considered.Message help can be formatted for the workstation using three format control characters.Each must be followed by a blank. • &N: Forces the message help to a new line, starting in column 2. If the help is longer than one line, the next lines are indented to column 4 until the end of the help or until another format control character is found. • &P: Forces the message help to a new line, indented to column 6. If the help is longer than one line, the next few lines start in column 4 until the end of the help or until another format control character is found. • &B: Forces the message help to a new line, starting in column 4. If the help is longer than one line, the next lines are indented to column 6 until the end of the help or until another format control character is found.Severity code (SEV)Specifies the severity code of the message being defined. The severity code indicates theseverity level of the condition that causes the message to be sent. (99 is the most importantseverity.)4-46 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty F6=Add (ADDMSGD) (2 of 4) IBM i Add Message Description (ADDMSGD) Type choices, press Enter. Message data fields formats: FMT _ Data type . . . . . . . . . . . . > *CHAR Length . . . . . . . . . . . . . > 3 &1 *VARY bytes or dec pos. . . . . . > 0 _ Data type . . . . . . . . . . . . > *CHAR Length. . . . . . . . . . . . . . > 10 &2 *VARY bytes or dec pos. . . . . . 0 + for more values _ Reply type. . . . . . . . . . . . . TYPE *CHAR Maximum reply length: LEN Length. . . . . . . . . . . . . *TYPE Decimal positions . . . . . . . More... F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 4-44. F6=Add (ADDMSGD) (2 of 4) OL209.0 Notes: If the values being described are intended to be used as MSGDTA of the SNDPGMMSG or SNDUSRMSG commands, the type must be *CHAR. Therefore, even numeric values must be represented in their character equivalent in parameter MSGDTA and described here in the FMT parameter as character. Message data fields formats (FMT) Specifies the formats of from 1 to 99 message data fields. Each field is described in this parameter by a list of attributes. All 99 of the message data fields can be used as substitution values in the message and message help defined in this message description. They can also be specified on the Data to be dumped prompt (DMPLST parameter) and the Alert options prompt (ALROPT) parameter) of this command. You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry field opposite the phrase “+ for more” and press the Enter key. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-47 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • The possible values are: • *NONE - No format is being described for message fields. If *NONE is specified, or if this parameter is omitted, no message data fields can be referred to in the First-level message text prompt (MSG parameter), Second-level message text prompt (SECLVL parameter), or Data to be dumped prompt (DMPLST parameter). • type (length (decimal-positions)) - The format of each message data field (up to a maximum of 99 fields) to be substituted in the message in this message description is defined by a list of attributes. These attributes specify the type of data in the field, the total length of the field, and, optionally, the number of decimal digits to the right of the decimal point. Certain data types do not require a length field. Boundary alignment requirements must be considered (for example, pointers are always aligned on 16-byte boundaries).Data TypeThe first value, type, specifies the type of data the substitution field contains and how thedata is formatted when substituted in the message text. The contents of the second andthird values vary depending on the type specified. One of the following types can bespecified for each field described on this parameter: • *QTDCHAR: A character string formatted with enclosing apostrophes (Monday, the 1st) is specified. • *CHAR: A character string formatted without enclosing apostrophes is specified. It is an alphanumeric string that can be used, for example, to specify a name (BOB). Trailing blanks are truncated. • *HEX: A string of bytes formatted as a hexadecimal value (XC0F4) is specified. • *DEC: A packed decimal number that is formatted in the message as a signed decimal value with a decimal point is specified. Values for length (required) and decimal positions (optional) are specified for this type (*DEC) to indicate the number of decimal digits and number of digits to the right of the decimal point. Zeros to the left of the first significant digit are suppressed, and leading blanks are truncated (removed). If a decimal position other than zero is specified, a decimal point is shown in the result even if the decimal precision in the result is zeros; examples are 128.00 and 128.01 if FMT(*DEC 5 2) is specified. If the number of decimal positions is not specified, zero is assumed. The following gives two examples: - If FMT(*DEC 2) is specified for a substitution field and the message data is a packed decimal value of X058C, the message text contains a positive value of 58 with no decimal point indicated. - If FMT(*DEC 4 2) is specified and the packed value is specified as X05810C (3 bytes long), the text contains the formatted decimal value of 58.10.4-48 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty • *BIN: A binary value that is either 2 or 4 bytes long (B0000 0000 0011 1010) and is formatted in the message as a signed decimal value (58) is specified. • *CCHAR: A character string that can be converted. If data of this type is sent to a message queue that has a coded character set identifier (CCSID) tag other than 65535 or 65534, the data is converted from the CCSID specified by the send function to the CCSID of the message queue. Conversions can also occur on the data of this type when the data is obtained from the message queue using a receive or display function. Refer to the Message Handler section of the National Language Support book, SC41-5101, for more details on CCSID conversions. The following formats are valid only in IBM-provided message descriptions and should not be used for other messages. • *DTS: An 8-byte field that contains date time stamp is specified. The date time stamp contains the date followed by one blank separator and the time. The date is formatted in the output message in the format specified by the system values QDATFMT and QDATSEP. The time is formatted as hh:mm:ss. • *SPP: A 16-byte space pointer to data in a space object is specified. When referred to in the DMPLST parameter, the data in the space object (from the offset indicated by the pointer) for the length specified, is dumped. *SPP is not valid as a replacement field in message text. • *SYP: A 16-byte system pointer to a system object is specified. When referred to in message text, the simple name of the system object is formatted as described in the name type, *CHAR. When referred to on the Data to be dumped prompt (DMPLST parameter), the object itself is dumped. • *ITV: An 8-byte binary field that contains the time interval (in seconds) for wait time-out conditions is specified. The time interval is formatted in the message as a zero-suppressed zoned decimal value (15 0) representing the number of seconds to wait. Length Following the type specification, a second value (length) can be specified to indicate the number of characters or digits that are passed in the message data. How the second value is used depends on the type specified in the first value. • If a length is not specified for *QTDCHAR, *CHAR, *HEX, or *SPP, then *VARY is assumed for the length. If *VARY is specified or assumed, the message data field passed by the SNDPGMMSG command must be preceded by a 2-byte or 4-byte binary field that indicates the actual number of bytes of data being passed. However, when *SPP is specified, the length field is contained in the first bytes pointed to by the space pointer. Therefore, the 2- or 4-byte field must precede the data pointed to by the space pointer, and not precede the space pointer that is passed as part of the message data. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-49 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • If the type *DEC is specified, the total number of decimal digits (including the fraction) must be specified as the second value; the number of digits in the fraction optionally can be specified (optional) as the third value. • If the type *BIN is specified, the message data field can be only 2 or 4 bytes long; the default is 2 bytes. • If the type *CCHAR is specified, the message data length field can be only *VARY. A variable length field is required because as the data in this field gets converted to different coded character set identifiers (CCSIDs), its length may change.Length field size/decimal positionsThe third value is used in one of two ways, depending on the type specified in the firstvalue:1. If *QTDCHAR, *CHAR, *CCHAR, *HEX, or *SPP is specified, and if *VARY is specified or assumed for the second value, the third value is used with *VARY to indicate the size of the length field actually passed. The third value can be either a 2 or a 4, which is the number of bytes used to specify the length (in binary) of the passed value.2. If *DEC is specified, the third value indicates the number of decimal positions in the decimal value. If not specified, the default is 0 decimal positions.Note: If an object has been damaged or deleted, the substitution variable is not replacedby the object name when it is displayed; instead, the variable appears as &n, wheren=number. Also, if the length of the message data that is passed to the substitution variableis shorter than the length specified, the substitution value becomes a null field.Reply type (TYPE)Specifies the type of valid values that can be made to an inquiry or notify message.The possible values are: • *CHAR - Any character string is valid. If it is a quoted character string, the apostrophes are passed as part of the character string. • *NONE - No reply type is specified. *NONE must also be specified on the Maximum reply length prompt (LEN parameter). • *DEC - Only a decimal number is a valid reply. • *ALPHA - Only an alphabetic string is valid. Blanks are not allowed. • *NAME4-50 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty - Only a simple name is a valid reply. The name does not have to be an object name, but it must start with an alphabetic character; the remaining characters must be alphanumeric. - Specifies the maximum length of a reply to an inquiry or notify message. The values specified apply only if one or more of the other validity checking parameters are specified. If none of the validity checking parameters are specified, the reply can contain up to 132 characters. - The possible values are: • *TYPE - The maximum length is determined by the type of reply specified on the Reply type prompt (TYPE parameter). The maximum length for each type of reply is: • Up to 32 characters are specified for types *CHAR and *ALPHA (132 characters if no additional validity checking is being performed). • Up to 15 digits are specified for *DEC, of which a maximum of 9 digits can be to the right of the decimal point. • Up to 10 alphanumeric characters are specified for *NAME. • *NONE - No reply length is specified. *NONE must also be specified on the Reply type prompt (TYPE parameter). • length (decimal-positions) - Specifies the maximum length allowed for the message reply. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-51 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook F6=Add (ADDMSGD) (3 of 4) IBM i Add Message Description (ADDMSGD) Type choices, press Enter. Valid reply values . . . . . . . . .VALUES *NONE _ + for more values ______________________ _ Special reply values: SPCVAL _ Original from-value . . . . *NONE _ Replacement to-value. . . . _ + for more values _ Range of reply values: RANGE Lower value. . . . . . . . *NONE _ Upper value. . . . . . . . _______________________ _ More... F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-45. F6=Add (ADDMSGD) (3 of 4) OL209.0Notes:Valid reply values (VALUES)Specifies a list of values of which one can be received as a valid reply to an inquiry or notifymessage. No more than 20 values can be specified in the list. Each value in the list mustmeet the requirements specified for message replies on the Reply type prompt (TYPEparameter) and the Maximum reply length prompt (LEN parameter). If this parameter isspecified, the Range of reply values prompt (RANGE parameter) and the Relationship forvalid replies prompt (REL parameter) cannot be specified.You can enter multiple values for this parameter. If you are on an entry display and youneed additional entry fields to enter these multiple values, type a plus sign (+) in the entryfield opposite the phrase + for more values and press the Enter key.Possible values are: • *NONE - No list of reply values is specified. • value4-52 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty - Specifies a list of up to 20 values to compare with a reply value that was sent in response to the message defined in this message description. The maximum number of each value is 32 characters. Special reply values (SPCVAL) Specifies a list of up to 20 sets of special values of which one set is used as the reply to an inquiry or notify message. The reply sent is compared to the from-value in each set; if a match is found, and a to-value was specified in that set, the to-value is sent as the reply. If no to-value was specified, the from-value is sent as the reply. The to-value must meet the requirements specified on the Reply type prompt (TYPE parameter) and the Maximum reply length prompt (LEN parameter). You can enter multiple values for this parameter. If you are on an entry display and you need additional entry fields to enter these multiple values, type a plus sign (+) in the entry filed opposite the phrase + for more values and press the Enter key. The possible values are: • *NONE - No special values are specified for the replies to this message. • from-value (to-value) - Specifies a list of up to 20 sets to determine the reply sent to the sender of the message. Range of reply values (RANGE) Specifies the upper and lower value limits for valid replies sent to an inquiry or notify message. These values must meet the requirements specified on the Reply type prompt (TYPE parameter) and the Maximum reply length prompt (LEN parameter), and both values must be of the same type. If this parameter is specified, the Valid reply values prompt (VALUES parameter) and the Relationship for valid replies prompt (REL parameter) cannot be specified. The possible values are: • *NONE - No range values are specified for the replies to this message. • lower-value upper-value - Specifies the lower and upper limit values for valid replies to this message. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-53 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook F6=Add (ADDMSGD) (4 of 4) IBM i Add Message Description (ADDMSGD) Type choices, press Enter. Relationship for valid replies: REL Relationship operator . . . . *NONE Value . . . . . . . . . . . . __________________________ _ Default reply value. . . . . . DFT *NONE ____________________________________________________________________________ ______________________ Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-46. F6=Add (ADDMSGD) (4 of 4) OL209.0Notes:Relationship for valid replies (REL)Specifies the relationship that must be met for a valid reply to an inquiry or notify message.The value specified must meet the requirements specified for replies on the Reply rangeprompt (TYPE parameter) and the Maximum reply length prompt (LEN parameter).If this parameter is specified, Valid reply values prompt (VALUES parameter) and theRange of reply values prompt (RANGE parameter) cannot be specified.The possible values are: • *NONE - No relationship values are specified for the replies to this message. • operator-value - Specifies one of the relational operators and the value against which the message reply is validity checked. • *LT - Less than4-54 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty • *LE - Less than or equal to • *GT - Greater than • *GE - Greater than or equal to • *EQ - Equal to • *NL - Not less than • *NG - Not greater than • *NE - Not equal to Default reply value (DFT) Specifies if the message is sent as an inquiry or notify message, the default reply that is used when the receiver of the message has indicated that all incoming messages are to receive default replies, or when a message is deleted from a message queue and no reply is specified. The default reply must meet the requirements specified for replies on the Reply type prompt (TYPE parameter) and the Maximum reply length prompt (LEN parameter). The possible values are: • *NONE - No default reply is specified for the replies to this message. • default-reply - Specifies the default reply to send (enclosed in apostrophes if it contains special characters). © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-55 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using a predefined message IBM i *PGM: APL030 APL030: PGM DCL &REC *DEC (3 0) /* NUMBER OF RECORDS */ DCL &RECA *CHAR 3 /* ALPHA NO. RECORDS */ DCL &FILE *CHAR 10 CHGVAR VAR(&RECA) VALUE(&REC) SNDUSRMSG MSGID(UAP0004) MSGF(APMSGF) TOMSGQ(*EXT) + MSGDTA(&RECA *CAT &FILE) MSGTYPE(*INFO) 2 0 0 A P L I N V *MSGF: APMSGF MSGID: UAP0004 MSG: &1 records processed in file &2 FMT: *CHAR 3 *CHAR 10 200 records processed in file APLINV. If 200 records is incorrect, run APLEDIT. Help © Copyright IBM Corporation 2010Figure 4-47. Using a predefined message OL209.0Notes:Predefined messages can be customized at execution time. Create a message descriptionwith substitution fields in its text that are filled in by the MSGDTA parameter.The FMT parameter of the message description defines the formats of the message datafields (substitution fields to be filled in at execution time). The message data fields can beused as substitution values in the first- and second-level message text. When specified inthe MSGDTA parameter of a SNDxxxMSG command, the data fields must beconcatenated into one character string that must match the format and sequence specifiedin the FMT parameter.4-56 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using a immediate message: SNDUSRMSG IBM i Is the backup tape mounted? (Y N) *EXT Type reply, press Enter. Reply . . . y message queue F3=Exit F12=Cancel Wait for reply. PGM /* Save AP library */ DCL VAR(&RESPONSE) TYPE(*CHAR) LEN(1) Translate to upper case. SNDUSRMSG MSG( Is the backup tape mounted? (y n) ) + VALUES(Y N) DFT(N) + MSGRPY(&RESPONSE) + TRNTBL(QSYSTRNTBL) + MSGTYPE(*INQ) defaults + TOMSGQ(*) IF COND(&RESPONSE = Y) THEN(SAVLIB LIB(APLIB) + DEV(TAP01) ) ENDPGM © Copyright IBM Corporation 2010 Figure 4-48. Using an immediate message: SNDUSRMSG OL209.0 Notes: The Send User Message (SNDUSRMSG) command is used by a program to send a message and optionally to receive a reply. The message can be immediate or predefined. This command combines parameters of the SNDPGMMSG and RCVMSG commands to allow the sending and receiving of a message from a program with a single command. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-57 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Predefined versus immediate messages IBM i Predefined Messages Immediate Messages Advantages Advantages Standardization Compose as you go Fill in the blanks, run time Can use on customization SNDMSG Easy to change SNDBRKMSG - No recompile Write once, use often Second-level text: Help key Severity level filtering Easy to back up Predefined DFT, VALUES, RANGE and REL if sent as *INQ or *NOTIFY © Copyright IBM Corporation 2010Figure 4-49. Predefined versus immediate messages OL209.0Notes:4-58 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Duplicate message ID method (1 of 2) IBM i Only one system reply list But you may compose your own unique replies in a message file. QCPFMSG MRGMSGF MYMSGF *MSGF copy a message *MSGF CHGMSGD: Change default reply OVRMSGF: Tell system to look at MYMSGF before QCPFMSG © Copyright IBM Corporation 2010 Figure 4-50. Duplicate message ID method (1 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-59 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Duplicate message ID method (2 of 2) IBM i 1 CRTMSGF MSGF(MYMSGF) 2 MRGMSGF FROMMSGF(QCPFMSG) TOMSGF(MYMSGF) SELECT(CPA7025) 3 CHGMSGD MSGID(CPA7025) MSGF(MYMSGF) DFT(C) 4 OVRMSGF MSGF(QCPFMSG) TOMSGF(MYMSGF) 5 CHGJOB INQMSGRPY(*DFT) 6 DLTJRNRCV JRNRCV(RCV0001) 7 The "C" reply will be taken for CPA7025, not the "I" reply. 8 CHGJOB INQMSGRPY(*RQD) © Copyright IBM Corporation 2010Figure 4-51. Duplicate message ID method (2 of 2) OL209.0Notes:1. CRTMSGF need only be done once, since it can hold many messages.2. MRGMSGF need only be done once to duplicate a message in the new message file.3. CHGMSGD need only be done once to change the default reply to the duplicatemessage.4. OVRMSGF and 5. CHGJOB need only be done once during the job.6. and 7. Commands and replies during the job.8. CHGJOB needs to be done when the job should revert back to requiring a reply toinquiry messages, instead of using the default.4-60 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Merge Message File (MRGMSGF) IBM i Merge Message File (MRGMSGF) Type choices, press Enter. From message file . . . . . . . FROMMSGF _________ Library. . . . . . . . . . . *LIBL To message file . . . . . . . . TOMSGF _________ Library. . . . . . . . . . . *LIBL Replaced message file . . . . . RPLMSGF *NONE Library. . . . . . . . . . . __________ Message IDs to select . . . . . SELECT *ALL + for more values __________ Message IDs to omit . . . . . . OMIT *NONE + for more values __________ Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 4-52. Merge Message File (MRGMSGF) OL209.0 Notes: The Merge Message File (MRGMSGF) command allows you to merge messages from one message file with those in another message file. Another message file may be specified to hold the messages that are replaced during the merging process. None of the message files specified are deleted by this command. Before the command is processed, messages can be in the from-message file (FROMMSGF), in the to-message file (TOMSGF), or in both files, but not in the replaced-message file (RPLMSGF). The three possibilities result in the following when the MRGMSGF command is processed: • When the messages are only in the FROMMSGF, they are added to the TOMSGF • When the messages are only in the TOMSGF, they remain in the TOMSGF • When the messages are in both the FROMMSGF and TOMSGF, the messages in the TOMSGF are first saved into the RPLMSGF (if a replace message file is specified); then, the messages in the TOMSGF are replaced by the messages in the FROMMSGF © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-61 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Override Message File (OVRMSGF) IBM i Override Message File (OVRMSGF) Type choices, press Enter. Message file being overridden . MSGF ______________ Overriding to message file . . .TOMSGF ______________ Library . . . . . . . . . . . *LIBL Secure from other overrides. . .SECURE *NO Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 4-53. Override Message File (OVRMSGF) OL209.0Notes:The Override Message File (OVRMSGF) command overrides a message file used in aprogram. The overriding message file is used (specified in the TOMSGF parameter)whenever a message is sent or retrieved and the overridden message file is specified.The overriding message file need not contain all the messages that the overridden filecontains. When a message is received or retrieved and the message identifier cannot befound in the overriding message file, the overridden message file is searched for theidentifier. Overriding message files can be overridden, resulting in a chain of overrides.This chain of overrides provides a list of message files that are searched when a messageis received or retrieved. Up to 30 message file overrides can be specified in a program.Message to be overridden (MSGF) • Specifies the name of the message file being used by the program to which this override command is applied. • Specifies the name and library of the message file that is used instead of the message file specified in the Message file being overridden prompt (MSGF parameter);4-62 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty alternately, if the names are the same, specifies that the value specified in the Secure from other overrides prompt (SECURE parameter) is used for the message file. Secure from other overrides (SECURE) • Specifies whether this file is secured from the effects of message file override commands used in earlier calls. If this parameter is not specified, processing occurs as if *NO had been specified. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-63 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Workstation exercises IBM i • Lab 10: Basic message handling (required) • Lab 11: Send user message command (required) © Copyright IBM Corporation 2010Figure 4-54. Workstation exercises OL209.0Notes:4-64 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 4.3. Working with messages © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-65 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Working with messages IBM i After completing this topic, you should be able to: • Code programs that use the MONMSG command • Understand and use the *ESCAPE message • Describe message a subfile • Use inquiry messages to control CL programs • Understand and use the system reply list © Copyright IBM Corporation 2010Figure 4-55. Working with messages OL209.0Notes:4-66 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Managing exceptions: User versus program IBM i *ESCAPE (error) , *NOTIFY , *STATUS , *NOTIFY or *STATUS messages Continue processing command No Yes Monitored? MONMSG: Program takes control. Perform command on EXEC parameter Other HLL: Similar capabilities Inquiry message CPA0701: R - Repeat command. I - Continue to next command. C - Cancel program. Function check CPF9999 sent to caller. © Copyright IBM Corporation 2010 Figure 4-56. Managing exceptions: User versus program OL209.0 Notes: When using a command in a program, view the online help text for the command to see the monitorable error messages it might generate. One cannot anticipate every error message that could be generated. While testing a program, you may find additional messages you wish to monitor. Monitoring the message and ignoring the error sometimes will do. Often, the program should do something to correct the error condition or end the program gracefully. A program-level MONMSG for CPF0000 will be activated by all escape notify and status messages beginning with letters “CPF”. RPG and COBOL provide the same kind of information in their I/O feedback areas. The lab requires the use of the System Request function; review it at this time if necessary. You can monitor for escape, notify, and status messages that are sent to your CL programs message queue by the commands in your program or in the programs that your program calls. The Monitor Message (MONMSG) command monitors the messages sent to the program message queue for the conditions specified in the command. If the condition exists, the CL command specified on the MONMSG command is run. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-67 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookEscape messages are sent to tell your program of an error condition that forced the senderto end. By monitoring for escape messages, you can take corrective actions or performcleanup operations and end the program. A program-level MONMSG for CPF9999(function check) is activated by escape messages that are not monitored by othercommand or program-level monitors. If the EXEC parameter is omitted, the programignores all unmonitored escape messages. This may be useful in testing, but not in aproduction environment. If an escape message is not monitored, eventually the workstationoperator (interactive) or system operator (batch) receives inquiry message CPA0701,whose options are: • Repeat the command. • Continue to the next command. • End the program and send a function check to the caller.A program-level MONMSG for CPF9999 (function check) is activated by escape messagesthat are not monitored by other command or program-level monitors. Before the messageCPF9999 is sent to the procedure, the original escape message is percolated to the otheractive procedures that are part of the same CL program. If the original escape messagehas not been handled by one of these active procedures, CPF9999 is then sent.4-68 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Monitorable error messages IBM i Check online Help for each command Example: Allocate Object (ALCOBJ) Allocate Object - Help Error messages for ALCOBJ *ESCAPE Messages CPF1002 Cannot allocate object &1. CPF1040 Maximum number of objects allocated on system. CPF1085 Objects not allocated. © Copyright IBM Corporation 2010 Figure 4-57. Monitorable error messages OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-69 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook MONMSG example: File availability IBM i PGM ALCOBJ OBJ( ( PAYLIB/PAYMAST *FILE *EXCL ) ) WAIT(0) MONMSG MSGID(CPF1002) EXEC(DO) SNDUSRMSG MSG( Program cannot run now because the + payroll master file is not available. ) + MSGTYPE(*INFO) TOMSGQ(*EXT) RETURN ENDDO CALL PGM(PAY02) DLCOBJ OBJ( ( PAYLIB/PAYMAST *FILE *EXCL ) ) ENDPGM © Copyright IBM Corporation 2010Figure 4-58. MONMSG example: File availability OL209.0Notes:This is a simple example of monitoring for a message. If the file is not available, aneasy-to-use message, instead of a system message, is sent to the operator, and then theprogram ends.If the Allocate Object (ALCOBJ) command cannot complete within the wait time (in thiscase, zero), then message CPF1002 is sent by the system. The Monitor Message(MONMSG) command gains control if CPF1002 is sent. The EXEC parameter ofMONMSG has the DO command, which begins a group of two commands, one to send amessage and one to end the program. The message is a more easy-to-use message thanCPF1002.4-70 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty MONMSG example: F3 or F12 during prompting IBM i PGM DCL &COUNT TYPE(*DEC) LEN(3 0) VALUE(0) . . . DOWHILE (&COUNT < 3) ?SNDMSG TOMSGQ(*REQUESTER) MONMSG MSGID( CPF6801 ) EXEC(DO) /*F3=Exit */ CHGVAR &COUNT (&COUNT + 1) ITERATE ENDDO LEAVE ENDDO ENDPGM © Copyright IBM Corporation 2010 Figure 4-59. MONMSG example: F3 or F12 during prompting OL209.0 Notes: If a command is preceded by a question mark in a CL program to prompt the user for parameters during program execution, MONMSG should check for the user ending the command with F3 or F12. CPF6801 does not appear in the monitorable messages for a command. However, if you prompt for a command then cancel it, you see in the job log or on the command entry screen that escape message CPF6801 was sent. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-71 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Monitor message command IBM i MONMSG MSGID( ) CMPDTA( ) EXEC( ) MSGID (required) MSGID(MCH1211) Only this message MSGID(CPF1600) CPF1601 - CPF16FF MSGID(CPF0000) CPF0001 - CPFFFFF MSGID(CPF9999) Function check: Will be activated by unmonitored escape message CMPDTA (optional) Example: MONMSG MSGID(CPF2182) + CMPDTA(PAYLIB) CPF2182 EXEC (optional) Not authorized to library &1 CL command Fmt *CHAR Len 10 © Copyright IBM Corporation 2010Figure 4-60. Monitor message command OL209.0Notes:The Monitor Message (MONMSG) command is used to monitor escape, notify, and statusmessages sent to the program message queue of the program in which the command isused. Completion and diagnostic messages cannot be monitored.When the MONMSG command is compiled in a CL program, it establishes a monitor forthe arrival of the specified messages. The command monitors the messages for thecondition specified by the comparison data given in the command. If a message meetingthe conditions arrives on the message queue, the CL command specified on the MONMSGcommand is processed.Up to 1000 MONMSG commands can be specified in a program to monitor the arrival ofmessages for specific conditions or for a group of conditions. Specific message identifiersor generic message identifiers can be monitored.The MONMSG command can be coded following most commands in the CL program. AMONMSG command that is not placed at the beginning of the program applies only to theimmediately preceding command; this is called a command-level MONMSG command. Ifthe message sent by that command meets the conditions specified in the MONMSG4-72 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty command, the action specified in the same MONMSG command is taken. As many as 100 MONMSG commands, coded immediately after a command, can monitor the messages sent by that command. When the action specified in the MONMSG command has been performed, and that action does not end with a GOTO or RETURN command, control returns to the command in the program that follows the command that sent the message. If the action ends with a GOTO command, control branches to the command in the program specified in the GOTO command. If the action ends with a RETURN command, control returns to the program that called the program that contains the MONMSG command. If one or more MONMSG commands are placed at the beginning of the program, immediately following the declare commands or the PGM command if there are no declare commands, they monitor messages sent by all of the commands in the program (maximum of 100). This is called a program-level MONMSG command. If any message sent by any command in the program meets the conditions specified in any one of the program-level MONMSG commands, the corresponding action specified in the same command is taken. The action taken by a command-level MONMSG command overrides a program-level MONMSG command. If a command is coded for the EXEC parameter on a MONMSG command that is placed at the beginning of a program, only the GOTO command can be used, and it must specify the label for the command to which control is to be passed if a monitored message occurs. If a command is not coded for the EXEC parameter, monitored messages are ignored. Restrictions: 1. This command is valid only in CL programs. 2. It can be coded after the last declare command (if declare commands are used), following the PGM command that begins the program, or it can be coded following any command allowed in CL programs, except for the following: DO, ELSE, ENDDO, ENDPGM, GOTO, IF, or RETURN. Note that if another program sends a message that is monitored by this command, a return cannot be made to that program. Message identifier (MSGID) Specifies the message identifiers of one or more escape, notify, or status messages that are to be monitored by this command. As many as 50 specific or generic message identifiers can be specified on one command. Note: Many CL commands issue one escape message for many different error conditions. Details about the error or failure are given in diagnostic messages that precede the escape message. Although diagnostic messages cannot be monitored, they can be received from the jobs external message queue after the escape message has activated the users message monitor. The first three characters of a message identifier must be a code consisting of an alphabetic character followed by two alphanumeric (alphabetic or decimal) characters; the © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-73 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebooklast four characters may consist of the decimal numbers 0 through 9 and the characters Athrough F. Note: Message identifiers using the MCH code (MCHnnn) use only the numbers 0 through 9 in the last four characters.If zeros are specified in either two or all four of the rightmost positions, such as ppmm00, ageneric message identifier is specified. For example, if CPF0000 is specified, all the CPFmessages are monitored.Specify the message identifiers of 1 to 50 messages that are monitored when they arrive atthis programs message queue.This is a required parameter.You can enter multiple values for this parameter. If you are on an entry display and youneed additional entry fields to enter these multiple values, type a plus sign (+) in the entryfield opposite the phrase “+ for more values” and press the Enter key.Comparison data (CMPDTA)Specifies the comparison data that is used to determine whether the monitored message(having one of the specified message identifiers) received on the programs messagequeue is acted on by this command. The message data specified in the MSGDTAparameter of the Send Program Message (SNDPGMMSG) command is compared with thiscomparison data. If the first part (up through the first 28 characters, or less) of themessages substitution values matches the comparison data specified, the action specifiedin the EXEC parameter of this command is taken. The action is also taken if no comparisondata is specified.Possible values are: • *NONE - No comparison data is specified. If the message in the programs message queue is from a command that this command is monitoring and if it has the specified identifier, the action specified by EXEC is taken. • comparison-data - Specifies a character string of no more than 28 characters, enclosed in apostrophes if necessary, that is compared with the same number of characters in the message data of the received message, starting with the first character in the message data. If the comparison data matches the first part of the received message data, this command performs the function specified in the EXEC parameter. A CL variable cannot be specified for the comparison data. - The comparison data can be displayed by the Display Program Variable (DSPPGMVAR) command.Command to execute (EXEC)4-74 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Specifies the CL command to be processed when a monitored message sent to the programs message queue meets the conditions specified and a monitored message arrives on the queue, the message is ignored, and control passes to the next command in the program. If the MONMSG command is placed at the beginning of the program, the EXEC parameter must specify the GOTO command and the label identifying the command that receives control. Specifies the CL command, including its parameters to be used, that is run when a message meeting the conditions specified in this command is received. The command specified is not run if the received message does not meet the specified conditions. A CL variable cannot be specified in place of the CL command. Note: If a DO command is specified on EXEC, the entire DO group associated with the DO command is run if the condition is met. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-75 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook MONMSG: Program level and command level IBM i PGM DCLF DCL DCL Program Level MONMSG Check here to see if message is monitored MONMSG Monitor message for all commands in program MONMSG EXEC(GOTO label) No EXEC: Ignore Command Command Command Level Check here first to see if the message is monitored MONMSG Monitor message for above command only MONMSG EXEC(most commands allowed) No EXEC: Ignore ENDPGM © Copyright IBM Corporation 2010Figure 4-61. MONMSG: Program level and command level OL209.0Notes:This figure distinguishes between command-level and program-level MONMSGcommands.If MONMSG commands are placed immediately after a command, they are command-levelmonitor message commands. They only monitor for messages generated by the commandthat proceeds them. The maximum number of MONMSG commands for a single commandis 100. The EXEC parameter is optional. Most commands are allowed in the EXECparameter of a command-level MONMSG. If the EXEC parameter is omitted, the messageis ignored.If a command generates a message which is not monitored by a command-levelMONMSG, the system looks in the group of MONMSG commands that immediately followthe declare statements. These are program-level monitor message commands. Themaximum number of program-level MONMSG commands per program is 100. The EXECparameter is optional. The only command allowed is GOTO. If the EXEC command isomitted, the message is ignored.A program can contain a maximum of 1000 MONMSG commands.4-76 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Following are the four cases of the EXEC parameter: • Program level, EXEC(GOTO command-label): The message is monitored anywhere in the program. When monitored, the program branches to the command label specified. • Program level, no EXEC parameter: the message is monitored anywhere in the program. If it is monitored, the error is ignored and the program continues with the command after the one that generated the error. • Command level, EXEC(CL command): Monitor for a message generated by the above command only. If it is monitored, run the command in the EXEC parameter. It does not have to be a GOTO command. Command level, no EXEC parameter: Ignore the error condition monitored and continue with the next command in the program. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-77 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Monitor message examples: Check object existence and authorization IBM i CHKOBJ OBJ(object-name) + OBJTYPE(CPF-object-type) + MBR(*NONE I *FIRST I database-file-member) + AUT(authorized-rights) EXAMPLES: 1 CHKOBJ OBJ(IWLIB/APR01) OBJTYPE(*PGM) /*EXISTENCE */ MONMSG . . . CHKOBJ OBJ(APPVEND) OBJTYPE(*FILE) + /*EXISTENCE */ 2 MBR(APPVEND) AUT(*DLT) /*AND AUTHORITY */ MONMSG . . . © Copyright IBM Corporation 2010Figure 4-62. Monitor message examples: Check object existence and authorization OL209.0Notes:Error messages for CHKOBJ *ESCAPE messages CPF9801 Object &2 in library &3 not found. CPF9802 Not authorized to object &2 in &3. CPF9810 Library &1 not found. CPF9815 Member &5 file &2 in library &3 not found. CPF9820 Not authorized to use library &1. CPF9830 Cannot assign library &1. CPF9899 Error occurred during processing of command.If the AUT parameter is specified, the CHKOBJ command is checking for both existenceand authorization. If the AUT parameter is omitted, the CHKOBJ command is checkingonly for existence.4-78 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Monitor message example IBM i PGM PAYLIB: /* Program level MONMSG */ MONMSG CPF9801 EXEC(GOTO ERROR) MONMSG CPF7302 /* Check for master files. */ CHKOBJ PAYMAST *FILE PAYMAST CHKOBJ GLMAST *FILE (must exist) /* New work file */ CHKOBJ QTEMP/WORK *FILE GLMAST (must exist) MONMSG CPF9801 GOTO OK DLTF QTEMP/WORK PAYTRAN OK: CRTPF QTEMP/WORK (Create new or /* New trans file if none exists */ use existing) CRTPF PAYLIB/PAYTRAN CALL PAYMONTHLY QTEMP: RETURN ERROR: SNDUSRMSG MSG( Master file missing. + (a) Check *LIBL for PAYLIB + WORK (New one each (b) See supervisor. ) MSGTYPE(*INFO) time) ENDPGM © Copyright IBM Corporation 2010 Figure 4-63. Monitor message example OL209.0 Notes: Note that message CPF9801, generated by the CHKOBJ command, is handled differently, depending on where the message is generated. Messages monitored in this program: • CPF9801 first-level message: Object &2 in library &3 not found. • CPF7302 first-level message: File &1 not created in library &2. Program logic: • The CHKOBJ command checks whether files PAYMAST and GLPMAST exist. If they do not exist, control goes to command label ERROR. • The program checks to see if the work file exists. If it does not exist, the program skips the step of deleting the old work file. File PAYLIB/PAYTRAN is created. If it already exists, the error message CPF7302 is ignored. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-79 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook MONMSG versus RCVMSG IBM i Message sent by the system or by a called program PGMA Monitor Message (MONMSG) –*ESCAPE, *NOTIFY, *STATUS only PGMA –Detect arrival –Control returns here immediately –Take action or ignore Receive Message (RCVMSG) –Does not take control as MONMSG does –Message contents copied to CL variables © Copyright IBM Corporation 2010Figure 4-64. MONMSG versus RCVMSG OL209.0Notes:Only message types status, notify and escape messages can be monitored. When amessage is monitored, control goes to the program monitoring the message. The messageID, and optionally, the compare data, describe the error condition. For unmonitored statusand notify messages, the sending program continues, while for unmonitored escapemessages, operator action is required.The RCVMSG command can copy information about the message, including messagetext, into CL variables. The RCVMSG command, however, is not activated automaticallyand does not receive control as MONMSG does. The program must explicitly execute it. Itmay be used with MONMSG to receive the contents of the message after MONMSGreceives control.RCVMSG has a WAIT parameter. A program can wait for a message to arrive on a queue(not necessarily a program queue), then continue.4-80 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Abnormally ending called program IBM i Program APL910 CALL APL920 Program logic determines Program APL920 APL920 must end abnormally. FAILURE Desired 1. End program APL920 2. Alert program APL910 3. APL910 manages the abnormal end © Copyright IBM Corporation 2010 Figure 4-65. Abnormally ending called program OL209.0 Notes: Suppose, due to application logic, that program APL920 should not or cannot continue. One way to manage this situation is to send an escape message from APL920 to APL910. This causes APL920 to end. APL910 must monitor the escape message and manage the situation. If APL910 does not monitor the escape message, it is sent the function check message (CPF9999) and ends also. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-81 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using an *ESCAPE message to end a program IBM i *PGM: APL910 MONMSG for *ESCAPE message sent by APL920 and/or CPF9999 function check *ESCAPE message sent by system 1 CALL APL920 3 Job Message 4 (From the system) Queue APL910 *PGM: APL920 *ESCAPE CPF9999 If desired function is not performed, the program should *ESCAPE end by sending an escape message: APL920 2 SNDPGMMSG MSGID( ) + MSGF( ) MSGTYPE(*ESCAPE) © Copyright IBM Corporation 2010Figure 4-66. Using an *ESCAPE message to end a program OL209.0Notes:1. Program APL910 calls APL920.2. Program APL920s logic determines that it cannot or should not continue and must end abnormally. It sends an escape message to its calling program, APL910. You can send escape messages from your CL procedure or program to the call message queue of the calling program or procedure with the SNDPGMMSG command. An escape message tells the caller that the procedure or program ended abnormally and why. The caller (APL910) can monitor for the arrival of the escape message and handle the condition it describes. When the caller handles the condition, control does not return to the sender of an escape message. If the caller is another procedure within the same program, the program itself does not end. The procedure to which the escape message was sent is allowed to continue. If the escape message was sent to the caller of the program itself, as in the case of this4-82 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty example, then all active procedures within the program (APL920) are ended immediately. As a result, the program cannot continue to run. 3. If the caller (APL910) does not monitor for an escape message, the default system action is taken. 4. A program-level MONMSG for CPF9999 (function check) will be activated by escape messages that are not monitored by other command or program-level monitors. Before the message CPF9999 is sent to the procedure, the original escape message is percolated to other active procedures that are part of the same CL program. If the original escape message has not been handled by one of these active procedures, CPF9999 is sent, which, if not monitored, ends the calling program (APL910). © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-83 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Sending an *ESCAPE message IBM i INV A LI D *ESCAPE MSG( ) MSGTYPE *NOTIFY *STATUS MSGID( ) MSGF( ) MSGDTA( ) IBM - supplied, blank, predefined message Message file . . . . . . . . . . . . . . : QCPFMSG Library: QSYS Message IDs: CPF9898 CPF9898 Message . . . . . &1 Cause . . . . . . This message is used by application programs as a general escape message Severity. . . . . . . . . . . . . . . . . . . : SEV 40 Message data field formats. . . . . . . . : FMT Field Data Type Length Vary Bytes or Dec Pos &1 *CHAR 512 SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) + MSGDTA( Program APL920 ended in error. ) + TOPGMQ(*PRV *) MSGTYPE(*ESCAPE) © Copyright IBM Corporation 2010Figure 4-67. Sending an *ESCAPE message OL209.0Notes:You cannot use the MSG parameter when sending an escape message. An escapemessage must be a predefined message. IBM-supplied message CPF9898 in *MSGFQSYS/QCPFMSGF is there for just this purpose.Message CPF9898 is intended for general use when you want to send an immediatemessage, but the sending command will allow only a predefined message. It has nomessage text except for a long substitution field. Therefore, by sending this message andsupplying your own text as the MSGDTA parameter, you may send an immediatepredefined message.4-84 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Standard way to display error messages IBM i Accounts Payable General Menu CL Program: Select one of the following: 1. MONMSG CPF0000 1. Vendor Inquiry 2. Display all of the 2. Vendor List programs messages 3. Item inquiry 4. Item list 5. Cash requirements listing Select Option _____ Reserve line(s) F3=Exit Cash requirements processing completed. Listing must be given to AP supervisor. Use a message subfile Discounts totaling 3332.65 are available. HELP © Copyright IBM Corporation 2010 Figure 4-68. Standard way to display error messages OL209.0 Notes: Multiple messages could be displayed through repetitive RCVMSG and SNDxxxMSG commands in the program. The message subfile technique is easier. It has these advantages: • It only requires a small amount (as little as one line) of reserved space on the display, thus not restricting application panel design. • The number of messages to display does not affect the display or the programming. • Second-level text is available. • The programming is not difficult. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-85 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Message subfile for error messages IBM i APL910: PGM MONMSG MSGID(CPF0000) GOTO ERROR CALL APL920 ERROR: SNDF Job Message Messages from Queue the system *EXT APL920: PGM APL910 Message Subfile SNDPGMMSG MSG( ) ... SNDPGMMSG MSG( ) ... SNDPGMMSG MSG( ) ... APL920 SNDPGMMSG MSGID( ) + MSGF( ) MSGTYPE(*ESCAPE) AP GENERAL MENU © Copyright IBM Corporation 2010Figure 4-69. Message subfile for error messages OL209.0Notes:Messages in a programs message queue could have been sent by the system or byanother program lower in the jobs program stack. The SNDF command fills and displaysthe subfile with all the messages in the programs message queue. Second-level text isavailable while the messages are displayed. By convention, they are displayed at thebottom of the workstation display. Menu uses this technique.4-86 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Message subfile DDS IBM i Field Function CA06(06 Display Messages ) TEXT( Accounts Payable + Control Clerk Menu ) OVERLAY R FMT900 R MENUSFL TEXT( Message SFL Data ) SFL Standard SFLMSGRCD(24) coding to MSGKEY SFLMSGKEY add to MENUPGMQ SFLPGMQ application R MENUSFLC TEXT( Message SFL Control ) display LOCK files SFLCTL (MENUSFL) SFLSIZ(50) SFLPAG(1) 51 SFLDSP 51 SFLDSPCTL 51 SFLEND 51 SFLINZ MENUPGMQ SFLPGMQ © Copyright IBM Corporation 2010 Figure 4-70. Message subfile DDS OL209.0 Notes: Modify keywords SFLMSGRCD, SFLSIZ, and SFLPAG to your standards. This code can be included in every display file, without change, if you standardize the lines you use to display the subfile and restrict your application display formats from using those lines. Modify SFLMSGRCD (starting line to display the subfile), SFLSIZ, and SFLPAG to your standards. • The keyword SFLMSGRCD identifies on which line the message subfile begins. • The keyword SFLSIZ identifies the number of messages the subfile can contain. • The keyword SFLPAG identifies how many messages are displayed at a time. • Place the keyword SFLMSGKEY as a field-level keyword for a user-defined field. This field will hold the message key. • The SFLPGMQ keyword is a field-level keyword for a user-defined field name into which you will put the programs name. • The SFLPGMQ keyword and its field (user-defined), must be in both the subfile record format and subfile control record format. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-87 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Message subfile programming IBM i APL910: PGM /* AP GENERAL MENU */ DCLF FILE(APD900) MONMSG MSGID(CPF0000) EXEC(GOTO SNDSFL) CHGVAR &IN51 1 CHGVAR &MENUPGMQ VALUE( APL910 ) START: SNDRCVF RCDFMT(FMT900) RMVMSG CLEAR(*ALL) /* CLEAR OUT OLD MESSAGES */ OPTION5: IF (&OPTION *EQ 5) DO CALL APL920 GOTO SNDSFL ENDDO SNDSFL: SNDF RCDFMT(MENUSFLC) /* FILL AND DISPLAY SUBFILE */ GOTO START ENDPGM Standard additions to application programs © Copyright IBM Corporation 2010Figure 4-71. Message subfile programming OL209.0Notes:A program that uses a message subfile should do the following: • Declare a character variable and give it a value that is the name of the program. In this example, &MENUPGMQ (associated with keyword SFLPGMQ in the display file) is assigned the name of the program. • Assign a value of 1 (true or on) to the logical variable that conditions keywords SFLDSP, SFLDSPCTL, SFLEND, and SFLINZ in the display file. • Fill and display the message subfile as desired: SNDF RCDFMT(message-subfile-control-format-name) • Clear out old messages as desired: RMVMSG CLEAR(*ALL)4-88 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty In this visual, arrows highlight the additional coding necessary in the program to manage the message subfile. If you wanted to remove all the messages from your *EXT message queue, all you would need is the following program: PGM RMVMSG PGMQ(*EXT) CLEAR(*ALL) ENDPGM © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-89 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Automatic replies to inquiry messages IBM i Desired: Automatic reply to a system generated *INQ message, different than the default reply Example: We would like any attempt to delete a journal receiver that has not been saved to automatically be canceled. CPA7025 Message: Receiver &1 in &2 never fully saved. (I C) Default reply: I © Copyright IBM Corporation 2010Figure 4-72. Automatic replies to inquiry messages OL209.0Notes:If a job causes an inquiry message to be generated, whether the message is sent by theprogram or the system, a user must type a response for the program to continue.Sometimes an automatic reply should be taken in order to run the program in batchunattended.4-90 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Where an inquiry message gets its reply IBM i INQMSGRPY INQMSGRPY INQMSGRPY *RQD *SYSRPYL *DFT NO MATCH? (SYSTEM REPLY LIST) YES REPLY REPLY REPLY *RQD reply *DFT *MSGQ YES DLVRY(*DFT) NO 1. SNDUSRMSG DEFAULT OPERATOR 2. *MSGF DEFAULT REPLY © Copyright IBM Corporation 2010 Figure 4-73. Where an inquiry message gets its reply OL209.0 Notes: This visual shows the logic the system uses in getting a reply for an inquiry message. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-91 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook System reply list method: System-wide table of replies IBM i SEQ NBR MSGID REPLY DUMP COMPARE VALUE 10 CPA2402 I *NO ADDRPYLE 20 CPA3138 I *NO PYPMAST CHGRPYLE RMVRPYLE 30 RPG1241 G *NO WRKRPYLE 35 CPA7025 C *NO 40 RPG1200 *DFT *NO 9999 *ANY *RQD *YES CHGJOB INQMSGRPY(*SYSRPYL) CHGJOBD © Copyright IBM Corporation 2010Figure 4-74. System reply list method: System-wide table of replies OL209.0Notes:Text for message CPA2402 is “Your group job is about to end.” Valid replies are C and I.The default is C.Text for message CPA3138 says that a file member has reached its maximum size. Validreplies are C and I. The default is C.For this example, an entry is added for the Receiver never fully saved (C/I)message, CPA7025, with a reply of C. The default is I.Sometimes, a job should run in unattended mode. To do so, replies must automatically betaken to inquiry messages. However, you may want to change the default replies of thesemessages. Possible values are: • Specific reply, such as I • *DFT: Use the default in the message description • *RQD: Require a response from the operator4-92 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty A default reply must meet the same validity checking criteria as the other replies for the message, or be specified as a special value in the message description. Default replies are used in these circumstances: • A message is received on a message queue that is in default delivery mode. CHGMSGQ ... DLVRY(*DFT) • DSPMSG displays the messages, then an inquiry message is removed using F11 or F13. • An inquiry message is generated by a job and the job has attribute INQMSGRPY(*DFT). • INQMSGRPY(*SYSRPYL) refers the message reply to the system reply list, which may specify a default. • Following are ways to change the default replies to inquiry messages: Change the default reply in the message description. This is not recommended for IBM messages. • Create a duplicate message description (except for the default) in another message file and use the override message file command. • Specify a default on the SNDUSRMSG command. • Assign a different default in the system reply list and change your job attribute to INQMSGRPY(*SYSRPYL). To change a default by creating a duplicate message description, do the following: 1. Create another message file. 2. Use MRGMSGF to add duplicate messages with different default values, to the new message file. 3. Use OVRMSGF to place the new message file ahead of the standard message file in the search list. OVRMSGF is a different kind of override than OVRDBF. You may override a file that has already been overridden, extending the search sequence. 4. Specify that default replies should be taken to inquiry messages. See the above discussion. There is only one system reply list on the system, so default replies cannot be customized by job with this method. The list is searched according to sequence number until an exact or generic match is made. For example, RPG1200 matches the range of messages RPG1200 to RPG1299. The reply specified for the matched entry is taken. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-93 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook System reply list method automatic C reply to CPA7025 IBM i CHGJOB INQMSGRPY(*SYSRPYL) DLTJRNRCV JRNRCV(RCV0001) Receiver RCV0001 in CLPLAB never fully saved. (I C) ?C Delete of receiver RCV0001 in CLPLAB canceled. © Copyright IBM Corporation 2010Figure 4-75. System reply list method automatic C reply to CPA7025 OL209.0Notes:1. The job looks to the system reply list for replies to inquiry messages2. An attempt is made to delete a journal receiver that has not been fully saved. a. Inquiry message CPA7025 is sent b. Automatic C reply is taken c. Escape message confirming the cancel is sent.4-94 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Workstation exercises IBM i • Lab 12: Monitor message (required) • Lab 13: Message programming (required) • Lab 14: Inquiry messages (recommended) © Copyright IBM Corporation 2010 Figure 4-76. Workstation exercises OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-95 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook4-96 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 4.4. User-written tools © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-97 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook User-written tools IBM i After completing this topic, you should be able to: • Understand file overrides • Write utility CL programs that process a database file © Copyright IBM Corporation 2010Figure 4-77. User-written tools OL209.0Notes:4-98 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty File overrides IBM i • OVRxxxF commands, for example: – OVRDBF – OVRPRTF – OVRMSGF • Temporary change to file name or attribute • Scope of override limited to job – OVRSCOPE parameter on OVRxxx command – Does not affect other jobs – Original program model (OPM) versus Integrated Language Environment (ILE) © Copyright IBM Corporation 2010 Figure 4-78. File overrides OL209.0 Notes: When a program is created, file are associated with it by the file names specified in the program (DCLF command). The IBM i allows you to override these file names or attributes of the file when you compile or execute the program. Overriding a file is different to changing a file. An override does not permanently change the attributes of the file. Overrides affect only those files opened within the single job in which they are defined. Any programs called within this job may be affected, but not programs within another user’s job or another submitted job. Overrides exist only until the end of the job in which they are issued. Overriding behaves differently for OPM programs (CLP type) versus ILE programs (CLLE type). © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-99 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Overriding name and attribute IBM i PGMA OVRDBF FILE(FILEA) + TOFILE(FILEB) + EOFDLY(*YES) (Declared) CALL PGMB FILEA PGMB (Used) DCLF FILEA RCVF FILEB © Copyright IBM Corporation 2010Figure 4-79. Overriding name and attribute OL209.0Notes:In this simple example, PGMB was coded and compiled to accept input from FILEA.However, at execution time, we wish to accept input from FILEB.Provided FILEA and FILEB have the same format, we can issue an OVRDBF command inPGMA to redirect input from FILEB.Note that we have also changed the attribute of the file as well as the name of the file beingused. We can achieve this in a single override. Multiple overrides to the same file would notgive us the desired outcome because they are not cumulative at the same call level.Changing the file name may be useful if the file has been renamed or moved to a differentlibrary since the program was compiled.Changing the attributes of a file is especially useful for printer files. The OVRPRTFcommand would be used for this.4-100 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty File override scoping IBM i • *ACTGRPDFN – Call-level scoping if requested from default activation group – Activation group scoping if requested from ILE activation group • *CALLVL – Call-level scoping for this override • *JOB – Use job-level scoping for this override *ACTGRPDFN OVRxxxF .... OVRSCOPE( *JOB *CALLVL © Copyright IBM Corporation 2010 Figure 4-80. File override scoping OL209.0 Notes: Overrides can be scoped to the: • Activation group level: *ACTGRPDFN - The scope of the override is determined by the activation group of the program that calls this command. When the activation group is the default activation group, the scope equals the call level of the calling program. When the activation group is not the default activation group, the scope equals the activation group of the calling program. • Call level: *CALLLVL - The scope of the override is determined by the current call level. All open operations done at a call level that is the same as or higher than the current call level are influenced by this override. • Job level: *JOB - The scope of the override is the job in which the override occurs. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-101 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Override termination IBM i • Return to calling program – OVRSCOPE(*CALLLVL) – CLP and OVRSCOPE(*ACTGRPDFN) • Job completion • End of activation group – CLLE and OVRSCOPE(*ACTGRPDFN) • Another override – Same file – Same call level – Not cumulative: Last override applies • DLTOVR command © Copyright IBM Corporation 2010Figure 4-81. Override termination OL209.0Notes:To avoid any undesirable affect of an override, you should use the DLTOVR command todelete the override as soon as you no further need of it.Do not rely on the system cleaning up automatically at the end of the program (*CALLLVL),end of the activation group (*ACTGRPDFN), or end of the job (*JOB).4-102 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using a database file for user-written utility programs IBM i PGM DCLF . . . DSPxxx . . OUTPUT(*OUTFILE) OUTFILE(MYFILE) + OUTMBR(*FIRST *REPLACE) DOWHILE 1 MYFILE RCVF MONMSG CPF0864 EXEC(LEAVE) /* CPF0864 IS THE END OF FILE MESSAGE */ /* PERFORM UTILITY FUNCTION */ ENDDO Same external : description as IBM model file : ENDPGM © Copyright IBM Corporation 2010 Figure 4-82. Using a database file for user-written utility programs OL209.0 Notes: Most DSPxxx commands allow output to a database file. This database file is a user file that is automatically created by the DSPxxx command and is externally described according to the IBM model file used by the command. An externally described database file can be read by a CL program. The main purpose of this capability is to allow users to write utility programs. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-103 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Declaring the database file IBM i *PGM DCLF FILE(IBM-file) /* PROGRAMMING: REFERENCE SUMMARY */ DSPxxx . . . OUTPUT(*OUTFILE) OUTFILE(user-file) OUTMBR(*FIRST *REPLACE) OVRDBF FILE(IBM-file) TOFILE(user-file) RCVF -or- user-file One time DSPxxx . . . OUTPUT(*OUTFILE) OUTFILE(user-file) OUTMBR(*FIRST *REPLACE) } setup *PGM DCLF FILE(user-file) DSPxxx . . . OUTPUT(*OUTFILE) OUTFILE(user-file) OUTMBR(*FIRST *REPLACE) RCVF © Copyright IBM Corporation 2010Figure 4-83. Declaring the database file OL209.0Notes:To use such a file in a CL program, do one of the following:1. Declare the IBM model file. Use the OVRDBF command to direct the program to use the file created in the program by the DSPxxx command.2. Use the DSPxxx command one time outside the program to create the file. Leave the file on the system. Each time the DSPxxx command is run, the records in the file are replaced.4-104 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Database file operations IBM i • Declare file: DCLF – Single format, PF or LF – Up to five per program • Open file – First RCVF – Input only • Read next record: RCVF – EOF message: CPF0864 • File closed – EOF – RETURN, TFRCTL © Copyright IBM Corporation 2010 Figure 4-84. Database file operations OL209.0 Notes: • CL variables are not changed when the program reads beyond the end of the file. • The end of file message on the RCVF command is CPF0864. • If the file is a non-field level database file, the record format contains one field. The record format and the field will have the same name as the file. • A database file is declared for input with the DCLF command. Up to five files (either database files or display files) may be declared per program. A database file must be a single-format physical or logical file. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-105 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Use an output file from a display command IBM i PGM PARM(&USER &LIB) DCL &USER *CHAR 10 DCL &LIB *CHAR 10 (1) DCLF QSYS/QADSPOBJ (2) DSPOBJD OBJ(&LIB/*ALL) OBJTYPE(*FILE *PGM *DTAARA) + OUTPUT(*OUTFILE) OUTFILE(QTEMP/MYFILE) (3) OVRDBF QADSPOBJ TOFILE(QTEMP/MYFILE) DOWHILE 1 (4) RCVF (5) MONMSG CPF0864 EXEC(RETURN) /* EXIT WHEN END OF FILE REACHED */ (6) GRTOBJAUT OBJ(&ODLBNM/&ODOBNM) OBJTYPE(&ODOBTP) + USER(&USER) AUT(*CHANGE) ENDDO /* GO BACK FOR NEXT RECORD */ DLTOVR QADSPOBJ DLTF MYFILE ENDPGM © Copyright IBM Corporation 2010Figure 4-85. Use an output file from a display command OL209.0Notes:The OVRDBF command replaces the name of a file or some of the files parameters whilethe program is using that file. It can be used to access files that have been renamed ormoved, or access a member of the file other than the first. In general, overrides remain ineffect from the time they are specified until they are replaced or deleted, or until theprogram in which they are specified ends.Specify the name of the file to be overridden in the FILE parameter. Use the TOFILEparameter only if the program refers to the file by another name. Any parameters specifiedon the OVRDBF command override those of the file.1. The declared file, QADSPOBJ in QSYS, is the IBM-supplied file that will be used by the DSPOBJD command. This file is the master file which is referenced by the command when creating the output file. It is referenced by the CL compiler to determine the format of the records and to implicitly declare variables for the fields in the record format.2. The DSPOBJD command creates a file named DSPOBJD in library QTEMP. This file has the same format as file QADSPOBJ.4-106 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 3. The OVRDBF command overrides the declared file to the file created by the DSPOBJD command. 4. The RVCF command reads the next sequential record from the file created by the DSPOBJD command. The values of the fields in the record are copied into the corresponding CL variables, which were implicitly declared by the DCLF command. 5. Message CPF0864 is monitored. This indicates that the end of file has been reached, so the program returns control to its caller. 6. The GRTOBJAUT command is processed, using the variables for object name, library name, and object type, which were read by the RCVF command. To see format QLIDOBJD of file QADSPOBJ, execute command DSPFFD QADSPOBJ. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-107 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Commands without an OUTFILE parameter IBM i Example: Process the output of WRKSYSSTS or DSPSYSSTS CRTPF FILE(MYSYSSTS) . . . DSPSYSSTS Output CPYSPLF Spooled or WRKSYSSTS Queue MYSYSSTS File OUTPUT(*PRINT) DCLF MYSYSSTS RCVF © Copyright IBM Corporation 2010Figure 4-86. Commands without an OUTFILE parameter OL209.0Notes:Most CL commands that produce information conducive to further processing allow you tospecify an OUTFILE parameter. For commands that do not have an OUTFILE parameter,you may process their output by specifying OUTPUT(*PRINT). Then, copy the spooled fileto a database file. Of course this will work for any spooled output.This approach is NOT recommended. The format of the printed output of an IBM displaycommand could change from release to release. (The file is not externally described.) Thisintroduces a significant maintenance burden for every version/release upgrade of IBM i(OS/400).CPYSPLF copies data records in the specified spooled output file to a user-defineddatabase file.The database file can be used to produce microfiche, be sent to another system, or beprocessed by a program. Some information is lost or changed.4-108 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty CPYSPLF...CTLCHAR(*FCFC) The first character of every record contains an ANSI control code. Use *FCFC if you intend to convert the data to microfiche or if CPYF is used to print the copied spool file. CPYSPLF...CTLCHAR(*PRTCTL) The first four characters of every record contain skip and space directions. Use *PRTCTL if a high-level language program such as an RPG or COBOL program is used to print the copied spool file. © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-109 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using QWCRSSTS API for system status IBM i PGM /* Call API QWCRSSTS to retrieve System Status */ DCL VAR(&BINVAR) TYPE(*CHAR) LEN(4) DCL VAR(&DECVAR) TYPE(*DEC) LEN(15 0) DCL VAR(&INTVAR) TYPE(*INT) LEN(4) DCL VAR(&RECEIVER) TYPE(*CHAR) LEN(140) DCL VAR(&FMT) TYPE(*CHAR) LEN(8) VALUE(SSTS0200) DCL VAR(&RESET) TYPE(*CHAR) LEN(10) VALUE(*NO) DCL VAR(&ERRORCODE) TYPE(*CHAR) LEN(16) DCL VAR(&SYSASP) TYPE(*CHAR) LEN(10) DCL VAR(&PCTASP) TYPE(*CHAR) LEN(10) /* Define RECEIVER and ERRORCODE lengths */ CHGVAR VAR(&INTVAR) VALUE(140) CHGVAR VAR(%BIN(&ERRORCODE 1 4)) VALUE(16) CALL PGM(QWCRSSTS) PARM(&RECEIVER &INTVAR &FMT + &RESET &ERRORCODE) /* Check return code for error */ CHGVAR VAR(&DECVAR) VALUE(%BIN(&ERRORCODE 5 4)) /* No error condition on API CALL - decode RECEIVER */ IF COND(&DECVAR *EQ 0) THEN(DO) CHGVAR VAR(&DECVAR) VALUE(%BIN(&RECEIVER 49 4)) CHGVAR VAR(&SYSASP) VALUE(&DECVAR) CHGVAR VAR(&DECVAR) VALUE(%BIN(&RECEIVER 53 4)) CHGVAR VAR(&PCTASP) VALUE(&DECVAR) SNDMSG MSG(System ASP : *BCAT &SYSASP *BCAT + %ASP Used *BCAT &PCTASP) TOUSR(*REQUESTER) ENDDO ENDPGM © Copyright IBM Corporation 2010Figure 4-87. Using QWCRSSTS API for system status OL209.0Notes:This example enables us to obtain information about the system status without using theDSPSYSSTS *PRINT command. We use the QWCRSSTS System API instead to retrievethe information through a parameter on the CALL command.The API approach is more flexible and protects our tools from future system changes. (Ifthe layout of the report produced by DSPSYSSTS *PRINT changes, we have to modify ourprograms.)There are now many thousands of APIs to complement DSPxxxx and RTVxxxxcommands. APIs are faster and more flexible and provide information about our systemotherwise unavailable through CL commands.4-110 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint (1 of 2) IBM i 1. The built-in function ________ and ________ variables are two methods of accomplishing the same goal; managing complex data structures. 2. The IBM i data area object, *DTAARA, a. is automatically created and deleted by the system. b. can be used to hold data for access by any job. c. can only be accessed by the job in which it was created. d. can hold integer data. 3. ?SNDMSG in a CL program a. can only be used with a declared display file. b. is equivalent to typing the command and pressing F4=prompt. c. denies *PUBLIC authority and access to the command. d. will not work in a CLP type of program. © Copyright IBM Corporation 2010 Figure 4-88. Checkpoint (1 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-111 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint (2 of 2) IBM i 4. _______ __________ can be retrieved into CL program variables for use in your programs. The retrieved values can also be changed by your programs. 5. True or False: A question mark preceding a command is equivalent to typing the command and pressing F4=prompt. 6. True or False: For program level MONMSG commands, the message is monitored if it occurs anywhere in the program. © Copyright IBM Corporation 2010Figure 4-89. Checkpoint (2 of 2) OL209.0Notes:4-112 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Workstation exercises IBM i • Lab 15: User-written tools (optional) © Copyright IBM Corporation 2010 Figure 4-90. Workstation exercises OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 4. Intermediate CL programming 4-113 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit summary IBM i Having completed this unit, you should be able to: • Write CL programs using the following techniques: – Built-in functions (%SWITCH, %SST, %ADDRESS, %OFFSET, and %BINARY) – Data areas – External attributes – Date conversion – Command prompting – Messages (immediate, predefined) – Monitor message commands – System reply list • Write utility CL programs that process the output of display commands © Copyright IBM Corporation 2010Figure 4-91. Unit summary OL209.0Notes:4-114 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 5. Batch jobs What this unit is about To insure the best response time for interactive jobs, remove work from interactive applications that are batch in nature. This unit explores methods of how to do this. What you should be able to do After completing this unit, you should be able to: • Create and invoke a program that is activated periodically and runs asynchronously from other jobs How you will check your progress • Exercises • Checkpoint questions © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit objectives IBM i After completing this unit, you should be able to: • Create and invoke a program that is activated periodically and runs asynchronously from other jobs © Copyright IBM Corporation 2010Figure 5-1. Unit objectives OL209.0Notes:5-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 5.1. Batch jobs © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Batch IBM i Separating batch functions from interactive applications PARM (S) Enter Order Print Order *DTAARA *DTAQ/*MSGQ Interactive Batch *USRSPC Pro gram *FILE © Copyright IBM Corporation 2010Figure 5-2. Batch OL209.0Notes:If the batch function is removed from interactive programs, the interactive programsperform better. The batch function should then be run in another job, asynchronously fromthe interactive job.If an interactive job also does work that is batch in nature, separate the two types of workand run the batch work as a separate batch job.Suppose an interactive application is accumulating information and periodically processingit. This figure shows an order-entry application. The order is entered line by line, and aninvoice is printed when it is complete.Printing an invoice is a batch function that should be removed from the interactiveapplication and run asynchronously from it. The interactive application performs faster if ithas to do less work.Periodically, the interactive job tells the asynchronous job that the data is ready to process.The asynchronous job must recognize that it has received a processing request, becomeactive, and process the data.5-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty For this process to work, some information has to be passed between the interactive job and the asynchronous (batch) task. While parameters are a very convenient and easy means of transferring this information, they are not the only method available to us. There are a number of other permanent objects which can also be used to communication information between separate tasks. Permanent objects for information transfer have the benefit that they persist after the job has been completed. This can be useful for problem diagnosis or application restart. This topic describes how to use a program variable, a data area, a data queue, and a database file as communication vehicles between an interactive job and an asynchronous job. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Batch jobs run asynchronously from interactive jobs IBM i Interactive Job P R O C E S S Batch Job PROCESS EOJ Batch Job P R O C E S S Wait PROCESS Wait PROCESS Wait Sources of batch jobs • Job from a job schedule object, ADDJOBSCDE • Subsystem autostart job • Submit job command, SBMJOB © Copyright IBM Corporation 2010Figure 5-3. Batch jobs run asynchronously from interactive jobs OL209.0Notes:This figure shows three timelines. The first timeline shows that an interactive job processesover a long period. The second timeline shows a batch job that is the result of a submit jobcommand. It processes a specific amount of information and then terminates.The bottom timeline represents a batch job that processes periodically. This job waits forinformation to arrive on a data queue or in a database file and then processes it. If no datais available, it waits.Start asynchronous jobs with either an auto-start job entry in a subsystem description, asubmit job command, or a job schedule entry.5-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty SBMJOB starts an asynchronous job: Use *LDA to pass information IBM i *LDA *LDA ORDER# ORDER# 12345 12345 *LDA ORDER 12345 INTER- BATCH ACTIVE SBMJOB JOB JOB END OF ORDER ORDERS *FILE © Copyright IBM Corporation 2010 Figure 5-4. SBMJOB starts an asynchronous job: Use *LDA to pass information OL209.0 Notes: The SBMJOB command copies the submitting jobs local data area to the submitted jobs local data area. In our order entry example, suppose the submitting job writes the order number of a just entered order in its local data area, then submits a batch job to print the invoice. The batch job has the order number in its local data area and can use it to find the order detail information in the order file. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Submit job overview IBM i SBMJOB JOB(JOBA) CMD(CALL PGMA) *LDA QBASE QBATCH OR *JOBQ QBATCH *SBSD *OUTQ WTR *DEVD CALL PGMA JOBA JOBA JOBA Job Message Queue for JOBA COPY OF COPY OF *LDA *LDA WRKSBMJOB © Copyright IBM Corporation 2010Figure 5-5. Submit job overview OL209.0Notes:Review the submit job process. Refer to the Work Management manual (in the InformationCenter) for more details. This figure provides an overview of the job flow for batch jobs.The CMD parameter of the SBMJOB command specifies one command to run. The JOBparameter identifies the name of the job. Use it to track that job. Specify a unique name inorder to track the jobs status easily. The command often is a CALL command to run aprogram.The command in the CMD parameter is put in the job message queue. The job is put on ajob queue, usually QBATCH. The initial value of the batch jobs *LDA is the value of thesubmitting jobs *LDA at the time of the SBMJOB command.When the batch job is selected for activation, it runs under the control of a subsystem,usually either QBASE or QBATCH. It may use its *LDA while it runs. If the job producesoutput, the output is normally placed on an output queue. If this output queue is connectedto a printer device through a writer program, the output is printed.5-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Parameters for SBMJOB and their defaults IBM i SBMJOB CMD(command) + parameters shown below Default to Default Other Defaults *CURRENT to *JOBD from SBMJOB PRTDEV JOB JOBD(*USRPRF) OUTQ JOBQ JOBPTY RTGDTA(QCMDB) USER OUTPTY RQSDTA(*CMD) PRTTXT LOG DSPSBMJOB(*YES) SYSLIBL LOGCLPGM MSGQ(*USRPRF) CURLIB CPYENVAR(*NO) INLLIBL INQMSGRPY SCDDATE DATE SCDTIME SWS SRTSEQ HOLD LANGID JOBMSGQMX CNTRYID JOBMSGQFL CCSID ALWMLTTHD SBMFOR © Copyright IBM Corporation 2010 Figure 5-6. Parameters for SBMJOB and their defaults OL209.0 Notes: Job attributes for submitted jobs come from the submit job command if they are specified. Otherwise, they come from one of three areas shown in the figure: • The current job (the one executing the submit job command) • The job description • The defaults on the submit job parameters © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Submit job example (1 of 2) IBM i Format: PROMPT Order Entry Invoice Number . . . . . . : 54321 (INVN) Shipping Instructions . . : SHIP VIA AIR (SHIP) Press Enter to Continue F3=Exit © Copyright IBM Corporation 2010Figure 5-7. Submit job example (1 of 2) OL209.0Notes:In this example, we have two CL programs.The (interactive) ORDERS program prompts the user to enter the desired invoice number(INVN) and shipping instructions (SHIP). The required variables are defined externally inthe display file (ORDERSDSP).5-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Submit job example (2 of 2) IBM i Interactive Job Batch Job ORDERSARA *DTAARA ORDERSARA *DTAARA 54321SHIP VIA AIR 54321SHIP VIA AIR ORDERS &INVNA &SHIP BATCHINV &INVNA &SHIP PGM PGM PARM(&TIME) DCLF ORDERSDSP DCL &SHIP *CHAR 15 DCL &INVNA *CHAR 5 DCL &INVNA *CHAR 5 DCL &TIME *CHAR 6 DCL &INVN *DEC (5 0) DCL &TIME *CHAR 6 SNDRCVF RCDFMT(PROMPT) IF (*NOT &IN03) THEN(DO) RTVDTAARA (ORDERSARA (1 5)) + CHGVAR &INVNA &INVN RTNVAR(&INVNA) CRTDTAARA ORDERSARA *CHAR 30 MONMSG CPF1023 RTVDTAARA (ORDERSARA (6 15)) + RTNVAR(&SHIP) CHGDTAARA (ORDERSARA (1 5)) &INVNA CHGDTAARA (ORDERSARA (6 15)) &SHIP CHGVAR &INVN &INVNA RTVSYSVAL QTIME &TIME CALL PRINTPGM PARM(&INVN &SHIP &TIME) SBMJOB CMD(CALL PGM(BATCHINV) + PARM(&TIME)) ENDPGM ENDDO ENDPGM © Copyright IBM Corporation 2010 Figure 5-8. Submit job example (2 of 2) OL209.0 Notes: In this example, program ORDERS writes an alphabetic invoice number and shipping instructions into ORDERSARA. The ORDERSARA data area is a permanent object which can be shared, like any other object, across jobs and programs. Program BATCHINV, running asynchronously as a batch job, retrieves the invoice number (alphanumeric) and shipping instructions from ORDERSARA. It then calls the HLL program (PRINTPGM) to produce the invoice. (CL cannot process printer files directly.) Note that &TIME is a character value. Decimal variables are not valid as parameters on a command within the CMD parameter of the SBMJOB command. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Using a data queue to communicate with an asynchronous job that has already started IBM i Have Interactive Program ORDER# Autostart/Batch Program ANY- ORDER# THING Enter order ORDER# ? CALL QRCVDTAQ CALL QSNDDTAQ DATA QUEUE Print order ORDER FILE © Copyright IBM Corporation 2010Figure 5-9. Using a data queue to communicate with an asynchronous job that has already started OL209.0Notes:QSNDDTAQ and QRCVDTAQ are IBM-supplied IBM i (OS400) programs. QCLRDTAQ isthe IBM-supplied program to call to clear a data queue. Pass two parameters to it, thename of the data queue and the name of the library.Data queues are an efficient object for job-to-job communication.In our example, the interactive application sends the order number of a completed order toa data queue. The asynchronous job (initiated by SBMJOB or as an autostart job) runs aprogram that waits for an entry to arrive on the data queue. When an entry arrives, theprogram becomes active and receives the data queue entry. It uses the contents of theentry to find the records for this order. After processing them, it branches back to the readinstruction.5-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Data queue facts IBM i *FIFO CRTDTAQ DTAQ( ) MAXLEN(1 TO 64,512) FORCE ( *NO *YES ) SEQ ( *LIFO ) • More efficient than "124 CALL QSNDDTAQ *FILE, *DTAARA, *MSGQ 123 • Not for long-term 122 storage • *CHAR values only 121 • Storage of removed 120 CALL QRCVDTAQ entries reusable but not -Wait for entry to arrive *DTAQ freed -Read and remove -Multiple jobs with receives • Regularly DLTDTAQ, pending CRTDTAQ • Any HLL program © Copyright IBM Corporation 2010 CALL QCLRDTAQ removes all Figure 5-10. Data queue facts OL209.0 Notes: API Retrieve Data Queue Message (QMHRDQM) retrieves an entry from a data queue without removing the entry. Like all queues, the contents of a data queue cannot be saved, but the data queue object can be saved. Data queues have been optimized to communicate between active programs, not to store a large volume of entries. They should not be used for long-term storage of data. Only one program receives a particular data queue entry, even if more than one program is waiting. When an entry is received from a data queue, the entry is removed, but the auxiliary storage is not freed. The same storage is used again when a new entry is sent to the data queue. The queue continues to grow if entries are sent but not received. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Create Data Queue (CRTDTAQ) command IBM i Create Data Queue (CRTDTAQ) Type choices, press Enter. Data queue . . . . . . . . . . . DTAQ > ____________ Library. . . . . . . . . . . . *CURLIB Type . . . . . . . . . . . . . . TYPE *STD Maximum entry length . . . . . . MAXLEN _____________ Force to auxiliary storage . . . FORCE *NO Sequence . . . . . . . . . . . . SEQ *FIFO Key length . . . . . . . . . . . KEYLEN _______ Include sender ID. . . . . . . . SENDERID *NO Remote data queue. . . . . . . . RMTDTAQ ____________ Library. . . . . . . . . . . . ______________ Remote location. . . . . . . . . RMTLOCNAME _________ APPC device description. . . . . DEV *LOC Local location . . . . . . . . . LCLLOCNAME *LOC Mode . . . . . . . . . . . . . . MODE *NETATR Remote network identifier. . . . RMTNETID *LOC More. . . F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 5-11. Create Data Queue (CRTDTAQ) command OL209.0Notes:The AUT and TEXT parameters are not shown here.The Create Data Queue (CRTDTAQ) command creates a data queue and stores it in aspecified library. Data queues, which are a type of IBM i (OS/400) system object, are usedto communicate and store data used by several programs either within a job or betweenjobs. Multiple jobs can send or receive data from a single queue. For more informationabout data queues on output queues, refer to the Printer Device Programming,SC41-5713.The CRTDTAQ command optionally creates a distributed data management (DDM) dataqueue when TYPE(*DDM) is specified. The DDM data queue is used as a reference dataqueue by programs to access data queues located on a remote (target) system in the DDMnetwork. Programs on the local (source) system refer to a remote data queue by the DDMdata queues name, not by the remote data queues name. The DDM data queue name,however, can be the same as the remote data queue name. The DDM data queue on thesource system contains the name of the remote data queue and the name of the remote(target) system on which the remote data queue is located.5-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Restriction: Users of this command must have add authority for the library where the data queue is located, object operational and add authority to the sending data queue, and use authority to the receiving data queue. Type (TYPE) • Specifies the type of data queue to be created. A standard data queue or a distributed data management (DDM) data queue can be created. • The possible values are: - *STD • A standard data queue is created. - *DDM • A DDM data queue is created. The data queue contains the name of the remote data queue accessed and the name of the remote (target) system that the data queue is located on. Maximum entry length (MAXLEN) • Specifies the maximum length of the entry that is sent to the data queue. Valid values range from 1 through 64,512. Notes: 1. If the data queue is associated with an output queue, the maximum length value should be at least 128. 2. This parameter is valid only when TYPE(*STD) is specified. This is a required parameter. Force to auxiliary storage (FORCE) • Specifies whether the data queue is forced to auxiliary storage when entries are sent or received for this data queue. • The possible values are: - *NO • Send and receive operations are not immediately forced to auxiliary storage. - *YES • Send and receive operations are immediately forced to auxiliary storage. Note: This parameter is valid only when TYPE(*STD) is specified. Sequence (SEQ) • Specifies the sequence in which entries are received from the data queue. Notes: 1. If the data queue is associated with an output queue, the sequence value should be *FIFO or *LIFO. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook2. The parameter is valid only when TYPE(*STD) is specified. • The possible values are: - *FIFO • Data queue entries are received in a first-in first-out sequence. - *LIFO • Data queue entries are received in a last-in last-out sequence. - *KEYED • Data queue entries are received by key. A key is a prefix added to an entry by its sender.Key length (KEYLEN) • Valid values range from 1 through 256. Specifies the number of characters in the key. Note: This parameter is valid only when SEQ(*KEYED) and TYPE(*STD) are specified.Include sender ID (SENDERID) • Specifies a sender ID to be attached to each message sent to the data queue. The ID contains the job name and the senders current user profile. • The possible values are: - *NO • Messages sent do not include the sender ID. - *YES • Messages sent include the sender ID. Note: This parameter is valid only when TYPE(*STD) is specified.Remote data queue (RMTDTAQ) • Specifies the name of the remote data queue on the target system. The data queue does not need to exist when the DDM data queue is created. • The possible values are: - remote-data-queue-name • Specifies the name of the data queue that identifies the remote data queue accessed. The name cannot exceed 10 characters.Remote location (RMTLOCNAME) • Specifies the name of the remote location that is used with this object. Note: Multiple DDM data queues can use the same remote location for the target system. The remote locations used must point to i systems that are at a release of IBM i (OS/400) that supports remote data queues. • The possible values are:5-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty - remote-location-name • Specifies the name of the remote location that is associated with the target system. The remote location, which is used in accessing the target system, does not need to exist when the DDM data queue is created but must exist when the DDM data queue is accessed. More information on remote locations is in APPC Programming, SC41-5443. APPC device description (DEV) • Specifies the name of the APPC device description on the source system that is used with this DDM data queue. The device description does not exist when the DDM data queue is created. • The possible values are: - *LOC • The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used. - device-name • Specifies the name of a communications device associated with the remote location. If the device name is not valid for the remote location, a message is first sent when the program device entry is required. More information on device names is in APPC Programming, SC41-5443. Local location (LCLLOCNAME) • Specifies the local location name. • The possible values are: - *LOC • The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used. - *NETATR • The LCLLOCNAME value in the system network attributes is used. - local-location-name • Specifies the name of the local location that is associated with the remote location. The local location name is specified only if the user indicates a specific local location for the remote location. If the local location name is not valid for the remote location, an escape message is sent when the DDM data queue is accessed. More information on local location names is in APPC Programming, SC41-5443. Mode (MODE) © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • Specifies the mode name that is used with the remote location name to communicate with the target system. • The possible values are: - *NETATR • The mode name specified in the network attributes is used. • Specifies the name of the mode that is used to communicate with the remote system. If the mode name is not valid for any combination of remote location and local location, an escape message is sent when the DDM data queue is accessed. More information on local location names is in APPC Programming manual in the Information Center.Remote network identifier (RMTNETID) • Specifies the remote network identifier (ID) in which the remote location resides that is used to communicate with the target system. • The possible values are: - *LOC • The remote network ID associated with the remote location is used. If several remote network IDs are associated with the remote location, the system determines which remote network ID is used. - *NETATR • The RMTNETID value specified in the system network attributes is used. - *NONE • No remote network ID is used. - remote-network-ID • Specifies the remote network ID that is associated with the remote location. The remote network ID is specified only if the user indicates a specific remote network ID for the remote location. If the remote network ID is not valid for the remote location, an escape message is sent when the DDM data queue is accessed. More information on local location names is in APPC Programming, SC41-5443.5-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Send data queue (QSNDDTAQ) API IBM i Parameters Required parameter group 1 Data queue name Input Char (10) 2 Library name Input Char (10) 3 Length of data Input Packed (5,0) 4 Data Input Char (*) Optional parameter group 5 Length of key data Input Packed (3,0) 6 Key data Input Char (*) 7 Asynchronous request Input Char(10) 8 Data is from journal entry Input Char(10) © Copyright IBM Corporation 2010 Figure 5-12. Send data queue (QSNDDTAQ) API OL209.0 Notes: • Data queue name - INPUT; CHAR(10) - The name of the data queue to send the data to. • Length of data - INPUT; PACKED(5,0) - The number of characters to be sent to the data queue. Note: An error occurs if the value specified is greater than the length specified by the maximum length (MAXLEN) parameter on the Create Data Queue (CRTDTAQ) command. • Data - INPUT; CHAR(*) - The data to be sent to the data queue. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Note: If the length of this field is larger than the length of data parameter, only the number of characters (beginning from the left) as defined by the length of data parameter are sent to the data queue. If the length of this variable is smaller than the length of data parameter, unexpected results can occur. • Length of data - INPUT; PACKED(3,0) - The number of characters in the key data parameter. Note: The maximum value is the value that is specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command. • Key data - INPUT; CHAR(*) - The data sent to the data queue. The value must be at least as long as the value specified in the length of key data parameters; otherwise, unexpected results can occur. • Asynchronous request - INPUT; CHAR(10) - Whether the send data queue request to a DDM data queue should be processed asynchronously. This parameter only applies to DDM data queues. Valid values are *YES and *NO. An error occurs if *YES is specified for a non-DDM data queue. If the value *YES is specified for the asynchronous request parameter for a DDM data queue and an error occurs on the operation, the error will not be detected until the next time the data queue is accessed. Note: If this parameter is specified, the key length and key data parameters must also be specified even if they are not applicable. In that event, the key length should be zero and blanks should be specified for the key data. • Data is from a journal entry - INPUT, CHAR(10) - Indicates whether the data, in parameter four, came from a journal entry. This parameter only applies to a non-DDM data queue. Valid values are *YES and *NO. - When using this parameter the data queue needs to have the same attributes as the journaled data queue. To ensure the attributes of the data queue are the same as the journaled data queue, save the journaled data queue and restore it to the system where this API will be called with optional parameter group 3 specified. For information about journaling, see the Journal management topic collection. - When *YES is specified for this parameter and the data for parameter four is from a data queue that was created with SENDERID(*YES), then the sender id information from parameter four will be used in the new data queue entry created by calling this API. That is, if the user in parameter four is different than the user calling this API,5-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty then the sender id associated with the new data queue entry will not contain the user that is calling this API. Note: When using this parameter, the length of data in parameter three should be obtained from the journal entry. The length could be longer than the maximum entry length of the data queue and this will be handled appropriately by the API, an error will not be issued. Note: If this parameter is specified, the key length, key data, and asynchronous request parameters must also be specified even if they are not applicable. In that event, the key length should be zero, key data should be blanks and *NO should be specified for the asynchronous request. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-21 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Receive data queue (QRCVDTAQ) API IBM i Parameters Required parameter group 1 Data queue name Input Char (10) 2 Library name Input Char (10) 3 Length of data Output Packed (5,0) 4 Data Output Char (*) 5 Wait time Input Packed (5,0) Optional parameter group 6 Key order Input Char (2) 7 Length of key data Input Packed (3,0) 8 Key data I/O Char (*) 9 Length of sender information Input Packed (3,0) 10 Sender information Output Char (*) 11 Remove message Input Char(10) 12 Size of data receiver Input Packed (5,0) 13 Error code I/O Char(*) © Copyright IBM Corporation 2010Figure 5-13. Receive data queue (QRCVDTAQ) API OL209.0Notes: • Length of data - OUTPUT; PACKED(5,0) - The number of characters received from the data queue. If a timeout occurs and no data is received from the data queue, this field is set to zero. The value of this field will never exceed the value specified for the MAXLEN parameter on the Create Data Queue (CRTDTAQ) command. - If the size of the data receiver variable is specified, the data received from the data queue will be truncated if the message is longer than the size of the data receiver variable. The value of this field is set to the actual length of the data received before it is truncated. • Data - OUTPUT; CHAR(*)5-22 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty - A field of at least the length of the value specified for the MAXLEN parameter on the Create Data Queue (CRTDTAQ) command. This field contains the data received from the data queue. Note: If the length of this field is larger than the size of the message received, only the number of characters (beginning from the left) as defined by the message received from the data queue are changed. If the length of this field is smaller than the value specified for the MAXLEN parameter on the Create Data Queue (CTRDTAQ) command, and the actual length of this field is not specified in the size of data receiver parameter, unexpected results can occur. If the length of this field specified in the size of data receiver parameter, the data received will be truncated if it is longer than the size specified. • Wait time - INPUT; PACKED(5,0) - The amount of time to wait if no entries exist on the data queue. - When no entries are on the data queue, the wait time parameter (in seconds) specifies the following: • <0 Waits forever. • 0 Continues processing immediately. If no entry exists, the call completes immediately with the length of data parameter set to zero. • >0 The number of seconds to wait. The maximum is 99999. which allows a wait time of approximately 28 hours. Note: If the wait time value is less than or equal to 2, the job does not leave the activity level (for 2 seconds). This is described as a short wait. For more details on activity levels and implementation applications, refer to the Work Management. • Key order - INPUT; CHAR(2) - The comparison criteria between the keys of messages on the data queue and the key data parameter. When the system searches for the requested key, the entries are searched in ascending order from the lowest value key to the highest value key until a match is found. If there are entries with duplicate keys, the entry that was put on the queue first is received. Valid values are: • GT Greater than • LT Less than • NE Not equal • EQ Equal • GE Greater than or equal • LE Less than or equal © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-23 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookThis parameter is ignored if the length of key data is zero. A value of blanks isrecommended if the length of key data is zero.For example, assume a keyed data queue contains these three entries: Physical entry 3-character key 1 GGG 2 XXX 3 AAAIf a key order of LE is specified with a key data of XXX, entry 3 would be received. If thesame values were specified on a subsequent request, entry 1 would be received. • Length of key data - INPUT; PACKED(3,0) - The length of the key data parameter. If this parameter is specified, it must be zero for nonkeyed data queues. For keyed data queues it must be equal to the length specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command. • Key data - I/O; CHAR(*) - The data to be used for receiving a message from the data queue. The key of the received message is also returned in this field. It may be different than the key specified to search for. For example, if the key data parameter is AA on the input with the key order parameter set to GE (greater than or equal to), the key of the record that is actually received could be AB or anything else greater than or equal to AA. The key data parameter is set to the actual key of the received data when the API returns. • Length of sender information - INPUT; PACKED(3,0) - The length of the sender identification parameter. Valid values are: • 0 No sender information is returned. • 8 Returns only the bytes returned and bytes available fields of the sender information. • >8 Return as much sender information as the length allows. • Sender information - OUTPUT; CHAR(*) - The sender ID information associated with the received message.The format and content of the sender information returned is shown in the following table.5-24 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Note: On the CRTDTAQ command, the SENDERID parameter defaults to *NO. To include the sender ID for each data queue entry, the SENDERID parameter must be *YES when the data is created. Offset  Offset  Type Field Dec Hex 0 0 PACKED(7,0) Bytes returned 4 4 PACKED(7,0) Bytes available 8 8 CHAR(10) Job name 18 12 CHAR(10) User profile name 28 1C CHAR(6) Job number 34 22 CHAR(10) Sender’s current user profile name Note: The last four fields, together, combine to make up the sender ID. Bytes available: The number of bytes of data available to be returned. All available data is returned if enough space is provided. Bytes returned: The number of bytes of data returned. Job name: The name of the job that sent the message. Job number: The job number of the job that sent the message. Senders current user profile name: The current user profile name of the job that sent the message. User profile name: The user profile name of the job that sent the message. • Remove message - INPUT; CHAR(10) - Whether the message is to be removed from the data queue when it is received. Valid values are: • *YES The message is removed from the data queue. This is the default value if this parameter is not specified. • *NO The message is not removed from the data queue. • Size of data receiver - INPUT; PACKED(5,0) - The size of the area to contain the data received from the data queue. If a value of 0 is specified for this parameter, no data is returned. If a size greater than 0 is specified, the data is copied into the receiver up to the specified length. If the available data is longer than the length specified, it is truncated. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-25 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook - If this parameter is not specified, the entire message is copied into the receiver variable. • Error code - I/O; CHAR(*) - The structure in which to return error information. For the format of the structure, refer to “Error Code Parameter” in System API Reference.5-26 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Data queue example: Sending IBM i CRTDTAQ DTAQ(MYLIB/MYDTAQ) MAXLEN(3) WRKSTNPGM DCL &Q *CHAR 10 VALUE(MYDTAQ) /*DATA QUEUE */ DCL &LIB *CHAR 10 VALUE(MYLIB) /*LIBRARY */ DCL &LEN *DEC (5 0) VALUE(3) /*DATA LENGTH */ DCL &DATA *CHAR (3) /*DATA */ 123 /* Value of &DATA determined by program 122 */ 121 124 CHGVAR &DATA ‘124’ *DTAQ CALL QSNDDTAQ PARM(&Q &LIB &LEN &DATA) © Copyright IBM Corporation 2010 Figure 5-14. Data queue example: Sending OL209.0 Notes: The sending program assigns the values of the length and data variables. To place information into the data queue, call the IBM-supplied program QSNDDTAQ and pass four parameters to it: 1. Data queue name (character, length 10) 2. Library (character, length 10) 3. Length of the entry (decimal, length(5 0)) 4. Data to be put in the entry (character) © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-27 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Data queue example: Receiving IBM i BATCHPGM DCL &Q *CHAR 10 VALUE(MYDTAQ) DCL &LIB *CHAR 10 VALUE(MYLIB) DCL &LEN *DEC (5 0) /* VALUES SUPPLIED */ DCL &DATA *CHAR 3 /* BY QRCVDTAQ */ 124 DCL &WAIT *DEC (5 0) VALUE(3600) CALL QRCVDTAQ PARM(&Q &LIB &LEN &DATA &WAIT) 123 DOWHILE (&LEN *GT 0) /*No time out. */ /*Process entry. */ 12 122 1 CALL QRCVDTAQ PARM(&Q &LIB &LEN &DATA &WAIT) ENDDO *DTAQ /* &WAIT expired ENDPGM &WAIT NEGATIVE: QRCVDTAQ WAITS INDEFINITELY © Copyright IBM Corporation 2010Figure 5-15. Data queue example: Receiving OL209.0Notes:The system assigns the value of the length variable when receiving. If the wait parameter isnegative, the program waits indefinitely. If the wait time expires, the value of the lengthvariable is assigned a value of zero and the program continues to its next instruction. Thelength variable should be checked to determine if the wait time has expired.To receive the contents of a data queue, call IBM-supplied program QRCVDTAQ and passfive parameters to it. The first four parameters are the same ones used for the (abovementioned) program QSNDDTAQ. However, you do not assign a value to the length anddata variables. The system supplies these values at the time the entry is received. The fifthparameter is the wait time in seconds. This is a five-position packed number. • Wait is *GE 0: The system waits the number of seconds specified. • Wait is *LT 0: The program waits indefinitely for an entry to arrive.When receiving data from a data queue, a program waits only until a data entry appears onthe data queue. This differs from using the EOFDLY parameter on the OVRDBF command,which causes the job to wait until the delay time ends before trying to read the next record.5-28 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Using a file to communicate with an asynchronous job that has already started IBM i BATCH PROGRAM PGM OVRDBF FILE(ORDERS) EOFDLY(60) CALL PRINT ENDPGM *FILE ORDERS PRINT 121 READ ORDERS INTER- 122 If at EOF, ACTIVE 124 123 wait EOFDLY time, then check for PROGRAM PRINT added record. ORDER FILE © Copyright IBM Corporation 2010 Figure 5-16. Using a file to communicate with an asynchronous job that has already started OL209.0 Notes: There is nothing new in the concept of storing information in a file by one program and reading it in another. However, the end of file delay (EOFDLY) parameter of the override database file command allows a program to wait for information to arrive in the file it is reading. EOFDLY specifies the number of seconds to delay when the end of file is reached before trying to read additional records. This delay is used to allow other jobs an opportunity to add records to the file and then have the new records processed without having to restart the job. When the delay time ends, the job is made active, and data management determines if any new records were added. If no new records were added, the job waits for another time delay without informing the application program. When this parameter is specified with a number of seconds, no end of file condition occurs using the read instruction. © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-29 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Considerations IBM i • Maxjobs of subsystem • Impact on the subsystem • Orderly means of program termination DAYEND: PGM END 01346 DCL &L *DEC ( 5 0) VALUE(3) /* LENGTH */ 01345 CALL QSNDDTAQ PARM( ORDERQ LIBX &L END) *DTAQ: ORDERQ CALL QRCVDTAQ PARM( ORDERQ LIBX &FLDLEN &DATA &WAIT) IF (&DATA *EQ END ) GOTO END END: ENDPGM © Copyright IBM Corporation 2010Figure 5-17. Considerations OL209.0Notes:An asynchronous job waiting for work will occupy one of the MAXJOBS jobs in thesubsystem. Perhaps MAXJOBS should be increased. If the job is started from a job queue,then the MAXACT of the job queue should be increased.A job that is waiting is taking up some of the system resources.You have to program an orderly means to end a waiting program. You should send an entryto the data queue or write a record to the database file that the program recognizes as thelast record in the file. The program can use this last record to end.5-30 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint IBM i 1. True or False: A data queue is optimized to communicate between active programs and is not intended for long-term storage. 2. The APIs ________ and ________ place data onto a data queue and read data from a data queue. 3. If the wait time for the QRCVDTAQ is a negative number, a. the system waits the number of seconds specified. b. the system does not wait for any amount of time. c. the system waits indefinitely for an entry to arrive. d. the system stops looking at the data queue for entries. 4. True or False: While communicating with asynchronous jobs, the use of data queues and data areas are mutually exclusive. © Copyright IBM Corporation 2010 Figure 5-18. Checkpoint OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-31 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint IBM i 1. True or False: A data queue is optimized to communicate between active programs and is not intended for long-term storage. 2. The APIs ________ and ________ place data onto a data queue and read data from a data queue. 3. If the wait time for the QRCVDTAQ is a negative number, a. the system waits the number of seconds specified. b. the system does not wait for any amount of time. c. the system waits indefinitely for an entry to arrive. d. the system stops looking at the data queue for entries. 4. True or False: While communicating with asynchronous jobs, the use of data queues and data areas are mutually exclusive. © Copyright IBM Corporation 2010Figure 5-19. Workstation exercises OL209.0Notes:5-32 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint solutions IBM i 1. True or False: A data queue is optimized to communicate between active programs and is not intended for long-term storage. 2. The APIs QSNDDTAQ and QRCVDTAQ place data onto a data queue and read data from a data queue. 3. If the wait time for the QRCVDTAQ is a negative number, a. the system waits the number of seconds specified. b. the system does not wait for any amount of time. c. the system waits indefinitely for an entry to arrive. d. the system stops looking at the data queue for entries. 4. True or False: While communicating with asynchronous jobs, the use of data queues and data areas are mutually exclusive. © Copyright IBM Corporation 2010 Figure 5-20. Unit summary OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 5. Batch jobs 5-33 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook5-34 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Unit 6. Commands What this unit is about User commands greatly simplify the interface between a user and a program.Additionally, users may modify IBM command defaults or write their interface to IBM commands. What you should be able to do After completing this unit, you should be able to: • Create user-defined commands with and without parameters How you will check your progress • Exercises • Checkpoint questions © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit objectives IBM i After completing this unit, you should be able to: • Create user-defined commands with and without parameters © Copyright IBM Corporation 2010Figure 6-1. Unit objectives OL209.0Notes:6-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty 6.1. Commands © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Commands IBM i • Command creation and execution • Defining parameters • Qualified name parameters • Changing existing commands © Copyright IBM Corporation 2010Figure 6-2. Commands OL209.0Notes:6-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Simple command OR (1 of 2) IBM i Selection or command ===> or Prompted command (F4 or ?) Order Entry (OR) OR - Source member in QCMDSRC: Source type CMD CMD PROMPT(Order Entry) - No keywords or parameters - Executes ORDERS program - Input screen for INVN and SHIP controlled by program © Copyright IBM Corporation 2010 Figure 6-3. Simple command OR (1 of 2) OL209.0 Notes: In the last unit we reviewed a simple example of SBMJOB. The interactive program ORDERS invited input of the fields INVN and SHIP using the PROMPT display file format. This information was then communicated to a second program through a data area. To execute the ORDERS program, we issued the CALL ORDERS command on the command line. To simplify the process further, we can provide an alternate command interface by defining our own command, OR, which invokes the ORDERS program. The OR command requires no parameters. Input values are still supplied through the PROMPT display format. Thus, there is no requirement for CL prompting (F4 or “?”). The OR command simply provides a shortcut for executing the ORDERS program. To create our user-defined OR command, we need to supply a minimum source code definition to the CRTCMD command. This source consists solely of the CMD statement. (Even the narrative order entry is optional.) © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Simple command OR (2 of 2) IBM i Create Command (CRTCMD) Type choices, press Enter. Command . . . . . . . . . . . . CMD > OR Library . . . . . . . . . . . *CURLIB Program to process command . . . PGM > ORDERS Library . . . . . . . . . . . *LIBL Source file . . . . . . . . . . SRCFILE QCMDSRC Library . . . . . . . . . . . *LIBL Source member . . . . . . . . . SRCMBR *CMD Threadsafe . . . . . . . . . . . THDSAFE *NO Multithreaded job action . . . . MLTTHDACN *SYSVAL Text description . . . . . . . TEXT *SRCMBRTXT Additional Parameters Current library . . . . . . . . CURLIB > OL20001 Bottom F3=Exit F4=Prompt F5=Refresh F10=Additional parameters F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 6-4. Simple command OR (2 of 2) OL209.0Notes:To create our OR command we must compile the source statements using CRTCMD (PDMoption 14).Note the command name OR need not be same as the program it will invoke, ORDERS.We have deliberately left the library name as *LIBL to retain flexibility.Note that CRTCMD allows us to specify a Current Library. This allows us to ensure thecorrect library is always in our library list when the OR command is use The necessaryobjects to support the command are then available.6-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty User-defined commands IBM i CALL PGMA PARM(_______ ____) or USRCMD KWD1( ) KWD2( ) or PGMA PGM PARM(_______ ____) DCL DCL . . . • Simplify entering parameters – Default values – Prompting – Validity checking – Help • Functions like an IBM command © Copyright IBM Corporation 2010 Figure 6-5. User-defined commands OL209.0 Notes: • Commands can call application programs eliminating the need for the CALL command. • Commands can set default values for parameters that are passed to an application program. • A command can validity check parameters before they are passed to an application program, eliminating editing that would otherwise have to be done in the application program. • Prompting for parameters, rather than having the user key them on the CALL, is a more easy-to-use interface. The user can be reminded of what each parameter means and does not have to remember the parameter sequence. • User, operator, or programmer tasks can be simplified by writing one simple command to run a frequently used command or series of commands. • User commands function just like IBM commands. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook User command example IBM i LABELS Source member in QCMDSRC CMD PROMPT(Label Writing Operation) PARM KWD(CUSNR) TYPE(*DEC) LEN(5 0) MIN(1) + PROMPT(Customer Number) PARM KWD(COUNT) TYPE(*DEC) LEN(3 0) DFT(20) + RANGE(10 50) PROMPT(Number of Labels) PARM KWD(FORMAT) TYPE(*CHAR) LEN(3) RSTD(*YES) + DFT(TWO) + SPCVAL((ONE) (TWO) (1 ONE) (2 TWO)) + PROMPT(One or Two Labels Across) Prompted command Label Writing Operation (LABELS) Type choices, press Enter. Customer Number . . . . . . . . Number Number of Labels . . . . . . . . 20 10-50 One or Two Labels Across . . . . TWO ONE, TWO, 1, 2 © Copyright IBM Corporation 2010Figure 6-6. User command example OL209.0Notes:This is the source for a user-defined command. Commands define parameters that arepassed to a command processing.This figure introduces the concept of the user-defined command. Suppose you have aprogram that produces labels and you need to pass to the program a customer number, anumber of labels, and an indication whether labels should be printed one or two across.A user could, of course, call this program and pass that information to the program on thePARM statement of the CALL command. Alternately, the programmer could write acommand definition source as shown at the top of the figure so that the user could beprompted as shown at the bottom of the figure.6-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Creating and running a command IBM i 1. Enter source program QCLSRC PGM MEMBER . STRPRTWTR... SP . ENDPGM 2. CRTCLPGM PGM(SP) SRCFILE(QCLSRC) SRCMBR(*PGM) Note: Program in any language 3. Enter command source QCMDSRC PARM... ELEM... CMD MEMBER QUAL... as needed . SP DEP... . PMTCTL... . 4. CRTCMD CMD(SP) PGM(SP) SRCFILE(QCMDSRC) SRCMBR(*CMD) 5. Run the command: SP, F4 © Copyright IBM Corporation 2010 Figure 6-7. Creating and running a command OL209.0 Notes: 1. Write the command processing program (CPP). It may be in any language. This is the program that does the work. 2. Create the CPP. 3. Enter the command definition statements (CMD, PARM, ELEM, QUAL, DEP, PMTCTL) that define the command parameters. Every command must have a command definition source, even if there are no parameters. At a minimum, a CMD statement must be in the source member. 4. Execute the CRTCMD command, identifying the command processing program (PGM parameter) and the command definition source (SRCMBR and SRCFILE parameters). 5. Run the command just like an IBM command. This new command can now be used in the same way as an IBM-supplied command (including prompting with F4). © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Create Command (CRTCMD) (1 of 3) IBM i Create Command (CRTCMD) Type choices, press Enter. Command . . . . . . . . . . . . > SP Name Library . . . . . . . . . . . *CURLIB Name, *CURLIB Program to process command . . . > SP Name, *REXX Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB Source file . . . . . . . . . . QCMDSRC Name Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB Source member . . . . . . . . . *CMD Name, *CMD Threadsafe . . . . . . . . . . . *NO *YES, *NO, *COND Multithreaded job action . . . . *SYSVAL *SYSVAL, *RUN, *MSG, *NORUN Text description . . . . . . . *SRCMBRTXT Additional Parameters Validity checking program . . . *NONE Name, *NONE Library . . . . . . . . . . . Name, *LIBL, *CURLIB More... F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010Figure 6-8. Create Command (CRTCMD) (1 of 3) OL209.0Notes:The Create Command (CRTCMD) command creates a new user-defined command (thatis, a command definition) that can use the same command processing support that is usedby IBM-supplied commands.Command (CMD) • Specifies the name and library of the command being created. This is a required parameter.Program to process command (PGM) • Specifies the name and library for the command processing program (CPP) used to process the command. The command processing program is not needed until command run time. • The CPP can be a compiled program written in any language. It can also be a REXX procedure. (REXX is another command-level language provided with i5/OS (OS/400). It is an interpreted language, not compiled.)6-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Create Command (CRTCMD) (2 of 3) IBM i Create Command (CRTCMD) Type choices, press Enter. Mode in which valid . . . . . . *ALL *ALL, *PROD, *DEBUG, *SERVICE + for more values Where allowed to run . . . . . . *ALL *ALL, *BATCH, *INTERACT... + for more values Allow limited users . . . . . . *NO *NO, *YES Maximum positional parameters . *NOMAX 0-75, *NOMAX Message file for prompt text . . *NONE Name, *NONE Library . . . . . . . . . . . Name, *LIBL, *CURLIB Message file . . . . . . . . . . QCPFMSG Name Library . . . . . . . . . . . *LIBL Name, *LIBL, *CURLIB Help bookshelf . . . . . . . . . *NONE Name, *NONE, *LIST Help panel group . . . . . . . . *NONE Name, *NONE Library . . . . . . . . . . . Name, *LIBL, *CURLIB Help identifier . . . . . . . . *NONE Character value, *CMD, *NONE Help search index . . . . . . . *NONE Name, *NONE Library . . . . . . . . . . . Name, *LIBL, *CURLIB More... F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 6-9. Create Command (CRTCMD) (2 of 3) OL209.0 Notes: Mode in which valid (MODE) • Specifies the modes of operating environment to which the newly defined command applies. One or more of the following modes can be specified. • *ALL The command is valid in all the types of modes: production, debug, and service. • *PROD The command is valid for production mode operations. • *DEBUG The command is valid for debug mode operations. • *SERVICE The command is valid for service mode operations. Where allowed to run (ALLOW) • Specifies where the command can be processed. One or more of the following options can be specified. • *ALL The command can be processed in a batch input stream, in a CL program, or when processed interactively. It can also be passed to the system program QCMDEXC (or QCAEXEC) for processing. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Note: User-created commands created in releases prior to REXX must be modified to work in REXX. • *BATCH The command can be processed in a batch input stream, external to a compiled CL program. • *INTERACT The command can be processed interactively, external to a compiled CL program. • *BPGM The command can be processed in a compiled CL program that is called from batch entry. • *IPGM The command can be processed in a compiled CL program that is called from interactive entry. • *BREXX The command can be processed in a REXX procedure that runs in an batch job. • *IREXX The command can be processed in a REXX procedure that runs in an interactive job. • *BMOD The command can be used in a batch CL ILE program only. • *IMOD The command can be used in an interactive CL ILE program only. • *EXEC The command can be processed as a parameter on the CALL command and can be passed as a character string to the system program QCMDEXC (or QCAEXEC) for processing. If *EXEC is specified, either *BATCH or *INTERACT must also be specified.Note that a message file (*MSGF) can be used to supply the prompt text. This makes iteasier to adapt commands to different applications or languages. Instead of changing thesource definitions for every command, only the message text has to be altered. This alsoavoids having to recreate the commands.Help text can also be provided for user commands. This is achieved using the same facilityas employed by IBM commands, enabling a consistent look and feel for all commands.Command help is supplied by panel group objects, (*PNLGRP) which are similar to displayfiles. However, instead of coding DDS source, *PNLGRP objects are created from UserInterface Manager (UIM) source statements. UIM is a tag language, similar to HTML andXML.Panel groups are beyond the scope of this course. Refer to the Display File Programmingreference manual for further details.6-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Create Command (CRTCMD) (3 of 3) IBM i Create Command (CRTCMD) Type choices, press Enter. Current library . . . . . . . . *NOCHG Name, *NOCHG, *CRTDFT Product library . . . . . . . . *NOCHG Name, *NOCHG, *NONE Prompt override program . . . . *NONE Name, *NONE Library . . . . . . . . . . . Name, *LIBL, *CURLIB Authority . . . . . . . . . . . *LIBCRTAUT Name, *LIBCRTAUT, *USE... Replace command . . . . . . . . *YES *YES, *NO Enable GUI . . . . . . . . . . . *NO *YES, *NO Bottom F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display F24=More keys © Copyright IBM Corporation 2010 Figure 6-10. Create Command (CRTCMD) (3 of 3) OL209.0 Notes: Current library (CURLIB) • Specifies the name of the current library associated with the job being run. Note: This library is also the current library when the validity checker program (if any) is processed for the command. • The current library does not change for the processing of this command. If the current library is changed during processing of the command, the change remains in effect after the command processing is complete. • The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the current library is restored to its previous value. If the current library is changed during command processing by the Change Library List (CHGLIBL) command or Change Current Library (CHGCURLIB) command, the change is effective only until the command is processed. QTEMP cannot be specified for the current library. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookProduct library (PRDLIB) • Specifies the name of the product library that is in effect during the processing of the command. Note: The product library for a command or menu remains in the library list while a command or menu is active unless another command or menu changes the product library. When a command or menu that changed the product library ends, the product library is restored to what it was when the command or library started. • The library need not exist when the command is created, but must exist when the command is processed. When command processing is completed, the product library is restored to its previous value. QTEMP cannot be specified for the product library.The ability to specify a particular current or product library allows us considerable flexibility.We can ensure that, whilst the command is in use, all required objects can be accessedthrough the library list. It therefore avoids us having to manipulate the library list explicitlywith CHGLIBL, ADDLIBLE, and so forth.6-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Command execution IBM i Parameter validation: No validity checker program Command Command IBM i Definition Command Object Analyzer *CMD Parms NO Error OK? YES Command Processing Program *PGM © Copyright IBM Corporation 2010 Figure 6-11. Command execution OL209.0 Notes: User-defined commands are processed the same way as IBM-supplied commands. The parameters are passed to the command analyzer. The analyzer validity checks them. If valid, control is given to the command processing program (CPP) and the parameters are passed to the CPP. If the parameters are not valid, an error message is retuned to the caller. If the command was entered interactively, the display station user can correct the parameters. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Command execution: No validity checker IBM i User Command versus Call Program Directly Prompt Cmd, F4 Prompt CALL PGM( ) PARM ( ) A IBM Command Analyzer Command No Definition Valid Parms? A Object *CMD Yes HLL CPP *PGM © Copyright IBM Corporation 2010Figure 6-12. Command execution: No validity checker OL209.0Notes:This visual shows us in more detail what happens in the previous flowchart.Note that the CPP could be called directly, without the benefit of parameter validitychecking.6-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty User command example IBM i LABELS Source member in QCMDSRC CMD PROMPT(Label Writing Operation) PARM KWD(CUSNR) TYPE(*DEC) LEN(5 0) MIN(1) + PROMPT(Customer Number) PARM KWD(COUNT) TYPE(*DEC) LEN(3 0) DFT(20) + RANGE(10 50) PROMPT(Number of Labels) PARM KWD(FORMAT) TYPE(*CHAR) LEN(3) RSTD(*YES) + DFT(TWO) + SPCVAL((ONE) (TWO) (1 ONE) (2 TWO)) + PROMPT(One or Two Labels Across) Prompted command Label Writing Operation (LABELS) Type choices, press Enter. Customer Number . . . . . . . . Number Number of Labels . . . . . . . . 20 10-50 One or Two Labels Across . . . . TWO ONE, TWO, 1, 2 © Copyright IBM Corporation 2010 Figure 6-13. User command example OL209.0 Notes: This example was presented earlier to introduce user-defined commands. Notice the coding in the command definition source and the corresponding effect it has on the prompt screen. The PROMPT parameter of the CMD statement allows you to put a heading (“Label Writing Operation”) on the top of the prompting display. Each parameter must have a PARM statement. The KWD parameter identifies the keyword that appears. There are three keywords: CUSNR, COUNT, and FORMAT. The TYPE and the LENGTH parameters of the PARM statements identify the data type and length, respectively, of the parameters. MIN(1) makes a parameter a required parameter. The DFT parameter supplies a default value. Notice that COUNT has a default of 20, which appears in the prompt display. COUNT must fall within the range of 10 - 50. If a user does not key a value within that range, an error message results. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student NotebookEach individual parameter may have its own prompt, specified by the PROMPT parameter.RSTD(*YES) restricts the parameter value to one of the values in the VALUES, SPCVAL,or SNGVAL parameters.SPCVAL((ONE) (TWO) (1 ONE) (2 TWO)): Either ONE or TWO are passed to the CPP. Ifthe user enters 1 or 2, those values are allowed, but are converted to ONE or TWObefore being passed to the CPP.In this example, choices rather than keywords are shown for each parameter. You mayswitch back and forth from choices to keywords with F11. The default is to show choices,unless the USROPT attribute of the user profile has *CLKWD specified.6-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Command source definition statements IBM i Name Description Required CMD COMMAND: Specifies prompt text for command Optional PARM PARAMETER: Defines a parameter ELEM ELEMENT: Elements of mixed list QUAL QUALIFIER: Describes one part of a qualified name DEP DEPENDENT: Relationships between parameters and their values PMTCTL Conditional parameter prompting © Copyright IBM Corporation 2010 Figure 6-14. Command source definition statements OL209.0 Notes: • The figure gives a brief description of the six statements that can be used in a command definition source. • Refer to the Information Center for further details on these commands. • CMD is required. A PARM statement is required for each parameter that is passed to the command processing program. The rest of the statements (ELEM, QUAL, DEP, and PMTCTL) further define a parameter that is initially defined with a PARM statement. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook PARM statement (1 of 4) IBM i PARM STATEMENT MAJOR KEYWORDS KWD Maximum of 10 characters TYPE *DEC, *CHAR, and so forth Statement Label: Points to QUAL or ELEM statements LEN Size of field MIN (0) (1) Is this a required parameter? FULL Like a CHECK(MF) field in DDS REL (*GT 500) RANGE (0 16) © Copyright IBM Corporation 2010Figure 6-15. PARM statement (1 of 4) OL209.0Notes:The PARM statement may have several keywords. Refer to the Control LanguageReference manual for a detailed description of each of the parameters on the PARMstatement. They are described briefly as follows: • The KWD parameter specifies the keyword name of the parameter being created. • The TYPE parameter specifies the type of value that can be specified for the parameter named in KWD. If TYPE(*NAME) is specified, the default length of such a parameter will be 10. • The LEN parameter specifies the length of the parameter value that is passed to the command processing program. • A qualified name is passed to the command processing program as a single field with the object name in the first 10 bytes and the library name in the second 10 bytes. • The MIN parameter specifies the minimum number of values that must be entered for the parameter being defined.6-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty • The FULL parameter specifies whether the number of characters in the parameter must be exactly the same as the number specified in the LEN parameter (if specified) or its default length (if LEN is not specified). • The REL parameter specifies the relationship between the parameter value of this parameter and the value of a constant or another parameter. • The RANGE parameter specifies the range or limits within which the value of the parameter must be. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-21 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook PARM statement (2 of 4) IBM i RSTD Can restrict the value to one of the values given in VALUES, SPCVAL, or SNGVAL VALUES List of constants, from which one can be entered SPCVAL Translates what the operator enters into what the program expects. Example: ((1 ONE) (2 TWO)) SNGVAL Allows a single value to replace a list Example: *ALL on some IBM commands DFT Default value for parameter, (cannot be specified if MIN(1)) © Copyright IBM Corporation 2010Figure 6-16. PARM statement (2 of 4) OL209.0Notes: • The RSTD parameter specifies whether the value entered for the parameter (specified in the PARM statement) is restricted to only one of the values given in the VALUES, SPCVAL, or SNGVAL parameters, or whether the value can be any value that satisfies the requirement specified by the TYPE, LEN, REL, RANGE, SPCVAL, SNGVAL, and FULL parameters. • The VALUES parameter specifies a list of 1 - 300 constants (fixed values) from which one constant can be entered as the value of the parameter named in KWD. • The SPCVAL parameter specifies a list of 1 - 300 entries that defines special values. They can be entered on the parameter named in a KWD. Each entry specifies a character string (from value) that can be entered even though it may not meet all validity checking requirements. • The SNGVAL parameter specifies a list of 1 - 300 single values. They can be specified for a parameter being defined as a mixed list or as a qualified name (when a statement labelled is specified for type). • The DFT parameter specifies the default value that is assigned to the parameter if a value is not specified by the user.6-22 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty PARM statement (3 of 4) IBM i ALWVAR Allow a variable name? PGM The parameter is the name of a program, data area or DTAARA file and should appear on DSPPGMREF for FILE any program using this command. © Copyright IBM Corporation 2010 Figure 6-17. PARM statement (3 of 4) OL209.0 Notes: • The ALWVAR parameter specifies whether to allow variable names for the parameter. • The PGM, DTAARA, and FILE parameters specify whether this parameter element is a program name, a data area name, or file name. This information is stored so that it can be included in the output of the display program references (DSPPGMREF) command. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-23 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook PARM statement (4 of 4) IBM i PROMPT What you see if you use F4 for prompting (30 characters maximum) PMTCTL Prompt for this parameter conditionally *PMTRQS: F10=Additional parameters ‘statement label’ of PMTCTL statement(s) CHOICE Parameter choices CHOICEPGM Program that supplies parameter choices © Copyright IBM Corporation 2010Figure 6-18. PARM statement (4 of 4) OL209.0Notes: • The PROMPT parameter specifies what prompt text, if any, is to be used for the parameter name by KWD. The prompt text further describes the keyword to the user. • The PMTCTL parameter specifies how prompting is controlled for this parameter. Prompting may be controlled using F10 or conditioned by another parameter specified by a PMTCTL statement referred to in the parameter TYPE(label-of-the-PMTCTL -statement). • The CHOICE parameter defines the text that is displayed in the possible choices field on the prompt screen. Up to 30 characters of text may be displayed. • The CHOICEPGM parameter specifies the qualified name of the program that is called during the prompting to fill in the possible choices, text, and the permissible values during prompting. This parameter must be specified if CHOICE (*PGM) is specified, and may not be specified otherwise.6-24 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty How command processing programs receive parameters: RPG IBM i How an RPG IV program would receive parameters from the example command LABELS presented earlier: RPG IV H DftActGrp(*No) // Prototype Definition D Labels PR D 5P 0 D 3P 0 D 3A // Procedure Interface Definition D Labels PI D Cust 5P 0 D Count 3P 0 D Format 3A © Copyright IBM Corporation 2010 Figure 6-19. How command processing programs receive parameters: RPG OL209.0 Notes: If the command processing program for the LABELS is an RPG program, this visual shows how it would be coded to receive the three parameters: • CUST: Packed decimal, length 5, decimal positions 0 • COUNT: Packed decimal, length 3, decimal positions 0 • FORMAT: Character, length 3 © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-25 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook How command processing programs receive parameters: COBOL and CL IBM i COBOL DATA DIVISION. LINKAGE SECTION. *PARAMETERS FROM COMMAND 01 CUST PIC S9(5) COMP-3 01 COUNT PIC S9(3) COMP-3 01 FORMAT PIC X(3). CL PGM PARM(&CUST &COUNT &FORMAT) DCL &CUST TYPE(*DEC) LEN(5 0) DCL &COUNT TYPE(*DEC) LEN(3 0) DCL &FORMAT TYPE(*CHAR) LEN(3) © Copyright IBM Corporation 2010Figure 6-20. How command processing programs receive parameters: COBOL and CL OL209.0Notes:If the command processing program for the LABELS command is a COBOL or CLprogram, this visual shows how it would be coded to receive the three parameters: • CUST: Decimal, length 5, decimal positions 0 • COUNT: Decimal, length 3, decimal positions 0 • FORMAT: Character, length 36-26 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Qualified name parameter IBM i PARM . . . TYPE(QUAL1) . . . *NAME object-name QUAL1: QUAL . . . TYPE ( *GENERIC *CHAR ) . . . *NAME ( ) library-name *GENERIC QUAL . . . TYPE . . . *CHAR object-name library-name QUAL has parameters similar to PARM. © Copyright IBM Corporation 2010 Figure 6-21. Qualified name parameter OL209.0 Notes: A qualified name is passed to the CPP as a single field, with the object name in the first 10 bytes and the library name in the second 10 bytes. To define a qualified name as a parameter, use a PARM and two QUAL statements, one for each part of the qualified name. The parameters on the QUAL statement have the same meaning that they do on the PARM statement. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-27 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Qualified name parameter example IBM i CMD PROMPT( WORK WITH OUTPUT QUEUE ) PARM KWD(OUTQ) PROMPT( OUTPUT QUEUE NAME ) + TYPE(Q1) MIN(1) Q1: QUAL TYPE(*NAME) QUAL TYPE(*NAME) MIN(0) SPCVAL((*LIBL)) + DFT(*LIBL) PROMPT( LIBRARY NAME) PGM PARM(&Q) DCL &Q *CHAR 20 DCL &OUTQ *CHAR 10 DCL &LIB *CHAR 10 CHGVAR &OUTQ %SST(&Q 1 10) CHGVAR &LIB %SST(&Q 11 10) ENDPGM WRKOUTQ &LIB/&OUTQ WORK WITH OUTPUT QUEUE (WQ) TYPE CHOICES, PRESS ENTER: OUTPUT QUEUE NAME . . . . . . . . . OUTQ __________ LIBRARY NAME . . . . . . . . . . . *LIBL ______ © Copyright IBM Corporation 2010Figure 6-22. Qualified name parameter example OL209.0Notes:Library name precedes object name in a qualified name with the following exceptions: • When being prompted, the object name is prompted before library. • When coding QUAL statements, the QUAL statement for the object name is coded first. • When a qualified name is passed to the command processing program, it is passed as one long field. The object name is in the first ten bytes and the library name is in the second ten bytes. • Qualified names are ALWAYS specified as library/object EXCEPT: 1. F4 prompting 2. QUAL statement 3. Qualified name passed to a command processing program • A qualified name requires one PARM statement and two QUAL statements.6-28 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty • The PARM statement should have prompt text for the object name. Its TYPE parameter points to the statement label of the first QUAL statement. If the object name is a required parameter, include parameter MIN(1) here. • The first QUAL defines the object name. Prompt text is not allowed. • The QUAL for the library immediately follows the QUAL for the object. Specify prompt text for library here. • In this example, the SPCVAL parameter is required because *LIBL does not follow the rules for a TYPE(*NAME) parameter. Notice that library is not required and, if omitted, *LIBL is the default value. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-29 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Changing existing commands IBM i CRTPRXCMD *CMD IBM and user commands PGM VLDCKR CHGCMD SEU + CRTCMD COMMAND IBM and user MODE user commands DEFINITION commands ALLOW STATEMENTS TEXT ALWLMTUSR CURLIB PRDLIB CHGCMDDFT IBM and user commands © Copyright IBM Corporation 2010Figure 6-23. Changing existing commands OL209.0Notes:If a command is changed, the programs in which it is used should be examined for theeffect of the change.Suppose you have a command and need to modify it. • Obviously, you may modify the source of the command definition, the CPP, or the validity checker and re-create the objects. • The CHGCMDDFT command allows changes to parameter default values without recreating the command. • The CHGCMD command allows changes to the command attributes without recreating the command.Refer to “Effect of Changing the Command Definition of a Command in a Procedure or aProgram” in chapter 9 of CL Programming.6-30 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Changing IBM commands: New release IBM i NEWRELEASE: PGM /* Run after new release installed. */ /* Changing command defaults */ DLTCMD USERQSYS/CRTCLPGM DLTCMD USERQSYS/SP CRTDUPOBJ OBJ(QSYS/CRTCLPGM) OBJTYPE(*CMD) NEWLIB(USERQSYS) CHGCMDDFT CMD(USERQSYS/CRTCLPGM) + NEWDFT( PGM(LIBA/*N) SRCFILE(LIBA/QCLSRC) LOG(*YES) ) /* Changing command name */ CRTDUPOBJ OBJ(QSYS/STRPRTWTR) OBJTYPE(*CMD) NEWLIB(USERQSYS) + NEWOBJ(SP) ENDPGM To use new command, *LIBL: USERQSYS QSYS • All jobs: CHGSYSVAL SYSVAL(QSYSLIBL) VALUE(USERQSYS QSYS...) • Within a job: CHGSYSLIBL LIB(USERQSYS) OPTION(*ADD) © Copyright IBM Corporation 2010 Figure 6-24. Changing IBM commands: New release OL209.0 Notes: Command defaults for user commands may be changed by changing the command source and recreating the command. Existing defaults for either IBM commands or user commands can be changed with the CHGCMDDFT command. If the defaults for an IBM command needs to be changed, create a duplicate command in a user library, change the defaults of the duplicate command, and then place the user library ahead of QSYS in the library list. CHGCMDDFT considerations: • The parameter must have an existing default. • The new default must be a valid parameter. • The new default may conflict with other parameter combinations. • Commands executed from system displays may use an IBM internal interface (instead of the command interface) to the requested function. Therefore, the changed defaults may not be used. Use F4 to prompt for the system command when you execute the command from a system display. In most cases, the specified default is used. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-31 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook • A new release of an IBM program product replaces all IBM commands for the program product. Therefore, you should use a CL program to duplicate IBM commands and make changes. Run the program after loading each new release. • IBM replaces commands with each new release. Therefore, before changing a command or its default, examine usage of the command you intend to change with PRTCMDUSG.6-32 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Restrict parameters of an IBM command: Example IBM i SNDBRKMSG MSG( ) TOMSGQ ( *ALLWS name(50) ) MSGTYPE ( ) *INFO *INQ RPYMSGQ( ) Desired restrictions: 1. Message type: *INFO File QCMDSRC Member SB 2. Send to only a single workstation CMD PROMPT( Send Break Message ) PARM KWD(MSG) TYPE(*CHAR) LEN(512) MIN(1) PARM KWD(WRKSTN) TYPE(*NAME) MIN(1) + SB, F4 PROMPT( Workstation name ) Send Break Message (SB) Type choices, press Enter. MSG__________ File QCLSRC Member SB Workstation name . . . . . WRKSTN_______ PGM PARM(&MSG &WS) DCL &WS *CHAR LEN(10) DCL &MSG *CHAR LEN(512) SNDBRKMSG MSG(&MSG) TOMSGQ(&WS) + MSGTYPE(*INFO) ENDPGM CRTCMD CMD(SB) PGM(SB) © Copyright IBM Corporation 2010 Figure 6-25. Restrict parameters of an IBM command: Example OL209.0 Notes: You can define your own commands to modify IBM-supplied commands: • Restrict the possible parameter values. Write a command whose command processing program uses parameter prefixes to restrict the parameter values of an IBM-supplied command. • Set default values for parameters. Write a command whose command processing program sets default values for parameters using parameter prefixes. • Create a command with a short name for a frequently run command that has a long name and uses several parameters. (For example, a user command SP that runs a CPP containing the STRPRTWTR ... command.) • You should not change IBM-supplied commands. Rather, duplicate the IBM command in a user library, make changes to the duplicate, and place the user library ahead of QSYS in the library list, as discussed previously. • A command can be rewritten in another language. © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-33 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Proxy commands: CRTPRXCMD IBM i COMMANDS • CRTPRXCMD • CHGPRXCMD • DLTCMD PARAMETERS • CMD(name) • TGTCMD(target command) • TEXT(‘ ‘) • AUT( ) • REPLACE( ) © Copyright IBM Corporation 2010Figure 6-26. Proxy commands: CRTPRXCMD OL209.0Notes:Proxy commands are used to create shortcuts to target commands.You can use the Create Proxy Command (CRTPRXCMD) to create a proxy command. Forparameters, you need to name your proxy command with the name (CMD) parameter. Youmust also identify a target command (TGTCMD). Optionally the following parameters arealso available: text description (TEXT), authority (AUT) and a replace command(REPLACE) option. Here’s an example of creating a proxy command that has a targetcommand of QSYS/DSPJOB, enter the following command:CRTPRXCMD CMD(MYLIB/PCMD1) TGTCMD(QSYS/DSPJOB) TEXT(‘dspjob proxy)Proxy commands do not allow you to specify command definition source as part of theirdefinition. Therefore, no parameter definition can be specified, nor prompt control. When aproxy command is used, all that information is inherited from the target command definedin the proxy command. You specify all the same parameters for the proxy command thatyou would for the target command. Use the Change Proxy Command (CHGPRXCMD)command, to change a proxy command. Use the Delete Command (DLTCMD) commandto delete a proxy6-34 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Checkpoint (1 of 2) IBM i 1. True or False: A user-defined command utilizes a command processing program (CPP) to do the work of the command. 2. The benefits of creating a command include which of the following? a. Eliminate the need for the call command. b. More user-friendly interface. c. Commands can set default values for parameters. d. All of the above. 3. If a command has a parameter, the ______ statement is required for each one of them. a. PARM b. QUAL. c. PROMPT d. CMD © Copyright IBM Corporation 2010 Figure 6-27. Checkpoint (1 of 2) OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-35 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint (2 of 2) IBM i 4. If a command has a parameter for which the value of that parameter names an object, the _________ statements are required. a. QUAL and SPCVAL b. PARM and QUAL c. PROMPT and CMD d. SNGVAL and SPCVAL © Copyright IBM Corporation 2010Figure 6-28. Checkpoint (2 of 2) OL209.0Notes:6-36 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookUempty Workstation exercises IBM i • Lab 18: Commands: Parts A, B, and C: Qualified name (recommended) © Copyright IBM Corporation 2010 Figure 6-29. Workstation exercises OL209.0 Notes: © Copyright IBM Corp. 1997, 2010 Unit 6. Commands 6-37 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit summary IBM i Having completed this unit, you should be able to: • Create user-defined commands with and without parameters © Copyright IBM Corporation 2010Figure 6-30. Unit summary OL209.0Notes:6-38 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Appendix A. Prerequisite and checkpoint solutions Unit 2 Prerequisite solutions Prerequisite review solutions (1 of 11) IBM i 1. What is an IBM i library? a. A physical disk storage area for objects b. The only structure on the i that is not an object c. A group of files d. A directory of objects © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-1 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review solutions (2 of 11) IBM i 2. For most object types, if no library is specified when the object is created, in which library is it placed? a. Current library b. Temporary library: QTEMP c. System library: QSYS d. General purpose library: QGPL © Copyright IBM Corporation 2010A-2 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Prerequisite review solutions (3 of 11) IBM i 3. When is a jobs library list used to find an object? a. Always b. Only if the library list has been replaced since sign-on c. Only if system value QUSRLIBL has value *LIBL d. Only if the object name is unqualified © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-3 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review solutions (4 of 11) IBM i 4. What command could you use to see your jobs library list? a. DSPLIBL b. DSPJOB c. EDTLIBL d. All of the above 5. What command can you use to alter your jobs library list? a. EDTLIBL b. ADDLIBLE c. CHGLIBL d. All of the above 6. Suppose you add library PAYLIB to your library list, then sign off. You sign on again. a. PAYLIB is not in your library list. b. PAYLIB is in your library list. c. PAYLIB is in your library list if you use the same password you did earlier. d. PAYLIB is in your library list if you use the same workstation as you did earlier. © Copyright IBM Corporation 2010A-4 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Prerequisite review solutions (5 of 11) IBM i 7. On a command line, keying a question mark (?) and pressing Enter, or using Function Key 4: a. Shows you a menu from which you can search for a command. b. Causes an error. c. Shows you the general help text. d. Shows you the valid function keys. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-5 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review solutions (6 of 11) IBM i 8. When an error message is displayed, you may move the cursor to it and press the Help key to: a. Take a default reply to the message. b. Remove the message. c. Send a copy of the message to the system operator. d. See additional information about the error. © Copyright IBM Corporation 2010A-6 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Prerequisite review solutions (7 of 11) IBM i 9. In SEU or in LPEX Editor, what line command allows you to key a new line? a. A (Add Line) b. I (Insert Line) c. M (More Lines) d. B (Blank Line) 10. Which function can SEU or LPEX Editor not perform? a. Check field names for correct spelling b. Syntax check source statements c. Globally change the spelling of a word d. Copy part of another source member to the one being edited © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-7 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review solutions (8 of 11) IBM i 11. While editing a source member with source entry utility (SEU), you remember a function of SEU, but cannot remember how to use it. You could: a. Move the cursor to the part of the SEU display in question and press the Help key. b. Examine the function key descriptions on the bottom of the display and try any that seem likely to help. c. Read the SEU Reference Manual. d. All of the above 12. Which of the following statements is true? a. Source programs are IBM i objects. b. A source file can contain only one source member. c. Source programs are members of source files, which in turn are objects in a library. d. Source programs are members of libraries. © Copyright IBM Corporation 2010A-8 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Prerequisite review solutions (9 of 11) IBM i Use the data description specifications below to answer the next two questions: A REF(FIELDREF) A CA03(03 Exit) A R PAYFMT1 A 5 30 Payroll A 8 11 Employee Number A EMPNO R I 8 30 A 9 11 Hours A HOURS R I 9 16 13. The above specifications are for what type of object? a. Printer file b. Display file c. Physical file d. Logical file 14. Which of the following statements is true? a. F3=Exit appears automatically on the display screen. b. The specifications are incorrect because EMPNO and HOURS have undefined field lengths. c. These statements must be compiled before they can be used. d. Function key 3 automatically ends the program. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-9 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Prerequisite review solutions (10 of 11) IBM i 15. The i definition of a batch job is: a. A job that requires no user interaction. b. A job that processes a batch of transactions. c. Both (a) and (b) d. A job that originates from a job queue. 16. The i definition of an interactive job is: a. From the start to the finish of a program run at a workstation. b. All work done at a workstation from sign-on to sign-off. c. All programs within a procedure. d. A program that interacts with the user. 17. What do the device description for a workstation, its interactive job, and its workstation message queue have in common? a. Their name b. Their authorization list c. Their owner d. Their library © Copyright IBM Corporation 2010A-10 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Prerequisite review solutions (11 of 11) IBM i 18. The stages of a batch job are: a. Job queue to active to output queue. b. Input queue to program to printer. c. Reader queue to storage pool to spooled file. d. Job description to routing entry to printer. 19. The display job command, DSPJOB, shows your jobs: a. Library list. b. Job log. c. Default output queue. d. All of the above. 20. The WRKSPLF command: a. Creates a spool file. b. Shows you all of your spooled output. c. Starts printing your spooled files. d. Works with system, printer, or logical files. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-11 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit 2 Checkpoint solutions Checkpoint solutions (1 of 2) IBM i 1. An implicit declaration of variables occurs a. when the DCL command is used to define variables. b. whenever CRTBNDCL is used to compile a CLLE source member. c. when the DCLF command is used to declare a file. d. when CRTCLPGM is used to compile a CLP source member. 2. The CHGVAR command can be used a. for arithmetic calculations. b. for converting data from one data type to another. c. for making character string data assignments. d. for all of the above. 3. Logical and relational expressions are either true or false. The system represents a true logical condition with a 1, and represents a false condition with a 0. © Copyright IBM Corporation 2010A-12 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Checkpoint solutions (2 of 2) IBM i 4. Which of the following is true when passing data to a CL program? a. Decimal constants always pass with a length of (15 5). b. Variables must be in the same sequence in the calling and called programs. c. Numbers passed as a character value, are enclosed in single quotes: ‘12345’. d. All of the above. 5. True or False: High level language (HLL) programs may call CL programs. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-13 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit 3 Checkpoint solutions (1 of 2) IBM i 1. True or False: The CRTBNDCL command creates a single module, ILE control language program from the specified CLLE source code. 2. True or False, it is also available on the CRTBNDCL and the CRTCLMOD commands: The parameter ALWRTVSRC, is available only on the CRTCLPGM command. 3. In order to get more detailed text for the error messages in your compile listing, you must specify *SECLVL for the OPTION parameter of the CRTBNDCL command. © Copyright IBM Corporation 2010A-14 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Checkpoint solutions (2 of 2) IBM i 4. The EVAL command, entered on the debug command line, a. will display the value for the specified variable. b. will display the attributes, length and data type, of a variable. c. will ‘watch’ the value of a variable every time it changes. d. will do nothing if the declared variable is part of a declared file. 5. True or False: The IBM i integrated debugger has similar function to the 5250 debug tool. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-15 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit 4 Checkpoint solutions (1 of 2) IBM i 1. The built-in function %SUBSTRING and defined variables are two methods of accomplishing the same goal; managing complex data structures. 2. The IBM i data area object, *DTAARA, a. is automatically created and deleted by the system. b. can be used to hold data for access by any job. c. can only be accessed by the job in which it was created. d. can hold integer data. 3. ?SNDMSG in a CL program a. can only be used with a declared display file. b. is equivalent to typing the command and pressing F4=prompt. c. denies *PUBLIC authority and access to the command. d. will not work in a CLP type of program. © Copyright IBM Corporation 2010A-16 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Checkpoint solutions (2 of 2) IBM i 4. External attributes can be retrieved into CL program variables for use in your programs. The retrieved values can also be changed by your programs. 5. True or False: A question mark preceding a command is equivalent to typing the command and pressing F4=prompt. 6. True or False: For program level MONMSG commands, the message is monitored if it occurs anywhere in the program. © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-17 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Unit 5 Checkpoint solutions IBM i 1. True or False: A data queue is optimized to communicate between active programs and is not intended for long-term storage. 2. The APIs QSNDDTAQ and QRCVDTAQ place data onto a data queue and read data from a data queue. 3. If the wait time for the QRCVDTAQ is a negative number, a. the system waits the number of seconds specified. b. the system does not wait for any amount of time. c. the system waits indefinitely for an entry to arrive. d. the system stops looking at the data queue for entries. 4. True or False: While communicating with asynchronous jobs, the use of data queues and data areas are mutually exclusive. © Copyright IBM Corporation 2010A-18 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4 Student NotebookAP Unit 6 Checkpoint solutions (1 of 2) IBM i 1. True or False: A user-defined command utilizes a command processing program (CPP) to do the work of the command. 2. The benefits of creating a command include which of the following? a. Eliminate the need for the call command. b. More user-friendly interface. c. Commands can set default values for parameters. d. All of the above. 3. If a command has a parameter, the ______ statement is required for each one of them. a. PARM b. QUAL. c. PROMPT d. CMD © Copyright IBM Corporation 2010 © Copyright IBM Corp. 1997, 2010 Appendix A. Prerequisite and checkpoint solutions A-19 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • Student Notebook Checkpoint solutions (2 of 2) IBM i 4. If a command has a parameter for which the value of that parameter names an object, the _________ statements are required. a. QUAL and SPCVAL b. PARM and QUAL c. PROMPT and CMD d. SNGVAL and SPCVAL © Copyright IBM Corporation 2010A-20 CL Programming for IBM i © Copyright IBM Corp. 1997, 2010 Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
  • V5.4backpg Back page