Week 6 CL Review

1. Week 6CL Review OS/400 Control Language (CL) provides a single, consistent, and flexible interface to many different system functions. Individual CL commands can be provided to certain classes of users and restricted from others based on their needs, by assigning users to a user-profile class and further restricting use through command object authority and authorization lists. Mastering the AS/400, Third Edition, author Jerry Fottral

2. Week 6CL Review (Continued) To summarize, CL: • Uses a single, consistent syntax • Can be entered from the command line, placed in CL programs, or included as part of a batch job A CL command name usually consists of a verb that identifies the action, a noun that specifies the object of the action, and, optionally, a modifier that limits or narrows the range of the command. Mastering the AS/400, Third Edition, author Jerry Fottral

3. Week 6CL Review (Continued) Command: DSPFD FILE(CATPF) CL syntax notation: Label Applies to Verb DSP Modifier F Noun D Keyword FILE Value CATPF Mastering the AS/400, Third Edition, author Jerry Fottral

4. Week 6CL Review (Continued) The operating system helps with the preparation and use of CL commands by providing: • Prompting support for all commands • Default values for most parameters • Validity checking to ensure correct entry • Extensive online Help for explanations of commands and parameters • Selective authorization by user, user class, and group profile Mastering the AS/400, Third Edition, author Jerry Fottral

5. Week 6CL Program Uses Most programs fall into one of three categories: • User interface -- CL programs can help give non-technical users an interactive interface that is simple and easy to use. Such an interface lets users request application functions and control application flow while insulating them from command-line access. With such a user interface, users do not require knowledge of CL or operating-system functions, and they can work with greater efficiency and less chance of error. Mastering the AS/400, Third Edition, author Jerry Fottral

6. Week 6CL Program Uses (Continued) • Operations -- Specific operational procedures are always required on any system. When you can write these regularly needed operational procedures in CL programs, they can then be tested and stored in an efficient form that requires only a single command or menu choice for consistent, error-free execution. Applications might range from procedures that select records from database files to be input to batch report programs, to procedures that selectively save objects or libraries to backup media at a certain time every night. Mastering the AS/400, Third Edition, author Jerry Fottral

7. Week 6CL Program Uses (Continued) • Job attributes -- Technical users and programmers may need to work in one of several different job environments that may require changes to job attributes. A user might need a special work screen after signing on. Use a CL program as the initial program to automatically tailor the environment after sign-on. This initial program can execute appropriate CL commands based on the user’s choice from a menu-like display screen. CL programs often manage “flow control” -- the sequencing, setup procedures, and error handling of related high-level language (HLL) programs in a multi-job-step application process. Mastering the AS/400, Third Edition, author Jerry Fottral

8. Week 6Advantages of CL Programs A CL program (an object of type *PGM) exists as an independent entity. Just like a compiled RPG or Cobol program, a CL program is in a “machine language” or a lower-level form that can be immediately executed. Mastering the AS/400, Third Edition, author Jerry Fottral

9. Week 6Advantages of CL Programs (Continued) Additional advantages include the following: • Some CL commands are available only from within a CL program. These include selection and iteration commands (e.g., IF-THEN, GOTO), error-testing commands (e.g., MONMSG), and file-processing commands (e.g., SNDRCVF). CL programs let you declare and work with variables and retrieve values (e.g., system values, job attributes, object descriptions) that will be used as variables in a program. Mastering the AS/400, Third Edition, author Jerry Fottral

10. Week 6 Advantages of CL Programs (Continued) Additional advantages include the following (continued): • You can test and debug CL programs just as you can HLL programs. Once checked out, CL programs always provide consistent, error-free execution because the sequence of commands and the logic become part of the actual program. If factors outside the program require the program to be changed, you can modify and re-compile the source CL program. Mastering the AS/400, Third Edition, author Jerry Fottral

11. Week 6 Advantages of CL Programs (Continued) Additional advantages include the following (continued): • CL programs can pass parameters to programs they call, and they can receive parameters passed from higher-level programs. This ability to pass and receive parameters makes CL programs very flexible and lets a single CL program meet the needs of different applications. Mastering the AS/400, Third Edition, author Jerry Fottral

12. Week 6Entering CL Source You enter CL programs as source members of source physical file QCLSRC using Source Entry Utility (SEU). When creating a new member (F6 from Work with Members Using PDM for QCLSRC), it is important to correctly specify the source type on the Start Source Entry Utility (STRSEU) screen. Mastering the AS/400, Third Edition, author Jerry Fottral

13. Week 6Entering CL Source (Continued) The source type for CL programs that we will be looking at is CLP -- the source type that is commonly used to create a *PGM object from each source member. (For CL programs designed to function in the Integrated Language Environment, or ILE, you use source type CLLE.) Mastering the AS/400, Third Edition, author Jerry Fottral

14. Week 6Entering CL Source (Continued) Once you are in SEU edit mode, entering each command is a little different than describing a ‘PF’ member in QDDSSRC. Because each CL command has its own unique prompt screen, the SEU line command IP for a CLP type is meaningless; if you enter it, SEU takes you to the Major Command Groups menu, just as if you had pressed F4 on a blank command line. Mastering the AS/400, Third Edition, author Jerry Fottral

15. Week 6Entering CL Source (Continued) Enter I to Insert a new line. Then type the command name (e.g., PGM) and press F4 if you need prompting -- this will take you to the command prompt screen for that command. There, you can fill out the parameter values. All commands have a Label parameter as the first parameter in the list, and this parameter lets you attach a tag or label to any command so you can refer to it as the object of a GOTO command from another location in the program. (Using the GOTO command along with the IF command is the only way to accomplish iteration control, or looping, in a CL program.) Mastering the AS/400, Third Edition, author Jerry Fottral

16. Week 6 Entering CL Source (Continued) When you have finished with the command prompt screen, pressing Enter adds the command (in keyword notation) to your SEU work screen and inserts another line for you. If the command and its parameters won’t fit on a single line, SEU inserts the continuation character (+) after a parameter and continues the command on the next line. Mastering the AS/400, Third Edition, author Jerry Fottral

17. Week 6CL Program Structure Depending on their function, CL programs can take many different forms, but a few general rules and guidelines apply. (See example showing the general structure of a CL program). • The program ID is not formalized in a CL program and must be entered using comments. Comments are any text on a line bracketed by a beginning /* and an ending */. The program ID should at least identify the program by name, briefly state the program’s purpose or function, and identify the program’s author. Mastering the AS/400, Third Edition, author Jerry Fottral

18. Week 6CL Program Structure (Continued) • The PGM statement (when needed) must be the first statement in the CL program, as it is required to list all CL variable names used to reference parameters passed to the program. • When the program receives no parameters, the PGM statement is optional, but it is usually used anyway. • When parameters are passed, the parameter-list variables in the called program must match the calling program’s parameter list positionally. Mastering the AS/400, Third Edition, author Jerry Fottral

19. Week 6CL Program Structure (Continued) • Each variable in the PGM parameter list of the called program must be identical to the calling program’s corresponding parameter in size and type. • The DCLF statement, if present, declares a file to be accessed by the CL program. • Only one file, regardless of type, can be accessed by a single CL program. It can be a display file or a database file. Mastering the AS/400, Third Edition, author Jerry Fottral

20. Week 6CL Program Structure (Continued) • DCL statements are used to declare variables needed by the CL program. Variables serve the same purposes in a CL program that they do in an HLL program -- counters, accumulators, indicators, or character strings. You can declare any number of variables in a single CL program. • DCLF and DCL statements, when present, must immediately follow the PGM statement and precede any other statements in the program. Mastering the AS/400, Third Edition, author Jerry Fottral

21. Week 6CL Program Structure (Continued) • Sequence operations are implemented by one CL command following another. • Practically any CL command can be executed in any required order, but there are certain restrictions. For example, you cannot include commands that require an interactive environment in a program that will be run in batch. Mastering the AS/400, Third Edition, author Jerry Fottral

22. Week 6CL Program Structure (Continued) • When multiple statements must be executed for a certain selection result, the statements must be blocked within a DO-ENDDO group structure. Iteration (loop control) is limited to the branching statement GOTO, when it is executed from within an IF statement. Specify the command label of the statement to which control passes after the GOTO command. Mastering the AS/400, Third Edition, author Jerry Fottral

23. Week 6CL Program Structure (Continued) • The ENDPGM statement, which is optional, marks the end of the CL program. When the program encounters this command, control returns to the calling program (or interactive job). Mastering the AS/400, Third Edition, author Jerry Fottral

24. Week 6Designing a CL Program (Walk through the Sample programs at this point). Mastering the AS/400, Third Edition, author Jerry Fottral

25. Week 6Declaring Variables Variables are explicitly declared in a CL program by the DCL (Declare) command. All variable names begin with the ampersand character (it is not necessary to declare variables made available through a file). Three types of CL variables exist: • Decimal (*DEC) for numeric packed-decimal variables • Character (*CHAR) for character or string variables • Logical (*LGL) for indicators that function as switches (on or off, true or false) Mastering the AS/400, Third Edition, author Jerry Fottral

26. Week 6Declaring Variables (Continued) Logical variables can have only the value '1' for on/true or '0' for off/false. When a variable is declared, only its name and type are required, but, except for *LGL variables, it is a good idea to explicitly include the length. Depending on the variable’s type, if you do not declare the variable’s length and value, they will default. Mastering the AS/400, Third Edition, author Jerry Fottral

27. Week 6Declaring Variables (Continued) Character variables default to a length of 32 and a value of spaces. Logical variables can have a length of only 1, so there’s no need to declare a LEN attribute for a logical variable. Variables are used in CL programs much the same as they are used in HLL programs -- to reference data items or as indicators, counters, accumulators, and working-storage items used for data manipulation, intermediate arithmetic results, type conversion, substring, or concatenation operations. Mastering the AS/400, Third Edition, author Jerry Fottral

28. Week 6Changing the Value of a Variable When a variable must be changed to a value other than its initial value or incremented by some arithmetic expression, you need the CHGVAR (Change Variable) command. The CHGVAR command has two required parameters: • VAR (Variable) parameter, which names the variable to be changed • VALUE parameter, which specifies the new value that the variable will assume. The value can be expressed as a constant, another variable, or an arithmetic or logical expression. Mastering the AS/400, Third Edition, author Jerry Fottral

29. Week 6 Changing the Value of a Variable (Continued) When you use an expression as the value, you must enclose it in parentheses. • You can use the CHGVAR command to convert from decimal to character types or, with caution, from character to decimal. A common reason for this type of conversion is to be able to display as part of a message a decimal variable value used as a counter or accumulator. Mastering the AS/400, Third Edition, author Jerry Fottral

30. Week 6 Changing the Value of a Variable (Continued) CHGVAR &CNTR (&CNTR + 1) If the variable &CNTR, shown above had been used to count the objects deleted in a certain library and you wanted to display that information as a message to the interactive job calling the program, you would first need to convert the information to character type. Mastering the AS/400, Third Edition, author Jerry Fottral

31. Week 6 Changing the Value of a Variable (Continued) If &CNTR were declared as a four-digit integer, you could declare a new variable as follows: DCL &ACNTR *CHAR 4 And after the count was completed, you could convert the numeric &CNTR to a character variable by coding CHGVAR &ACNTR &CNTR This command would place the character equivalent of the packed-decimal value in &CNTR into the character variable &ACNTR. Mastering the AS/400, Third Edition, author Jerry Fottral

32. Week 6 Changing the Value of a Variable (Continued) The value could then be concatenated to a message and sent to a message queue or job, using a command such as SNDPGMMSG MSG(&ACNTR *BCAT 'objects have been deleted') Mastering the AS/400, Third Edition, author Jerry Fottral

33. Week 6Selection and Iteration To implement selection in CL programs, use the IF statement. The syntax of a simple IF statement is: IF (condition) THEN(command) The condition can be a simple relational or logical expression, a negated expression using the logical operator *NOT, or a combined expression using the logical operators *AND and *OR. Mastering the AS/400, Third Edition, author Jerry Fottral

34. Week 6File I/O in CL Programs CL programs can access two types of files: display files and database files, both physical and logical. A single CL program can declare only one file, and that file must exist at the time the CL program is compiled. When the program is compiled, data fields from the file are made available to the program as variables. Mastering the AS/400, Third Edition, author Jerry Fottral

35. Week 6Sending Messages A message is a communication sent from a program or a user to a message queue. A message queue functions like a mail box to hold the incoming message until it can be handled. Every user on the system has a message queue identified by the same name as the user ID, and when you sign on and start an interactive job, your workstation message queue also becomes available. Mastering the AS/400, Third Edition, author Jerry Fottral

36. Week 6 Sending Messages (Continued) These are permanent message queues that continue to exist after you sign off and when the terminal is not in use; if you return to examine these message queues from a later session, they will still be there, and the old messages will still be available (unless they were deleted). In addition to these message queues, every running program has a program message queue that is created when the program starts and is deleted when the program ends. Mastering the AS/400, Third Edition, author Jerry Fottral

37. Week 6Sending Messages (Continued) Every job has an external message queue that is created when the job starts and is available during the life of the job. An external message queue is often used to display an inquiry message (one requiring a reply) when a CL or HLL program experiences a severe runtime error during testing. Mastering the AS/400, Third Edition, author Jerry Fottral

38. Week 6Sending Messages (Continued) Several types of messages exist, but we mention only two here: informational and inquiry. Informational messages are just that -- they inform the recipient of some condition or convey the results of a process. They are not usually used for error messages and do not require a response. On the other hand, inquiry messages request a response and are often used to display error messages that require a reply. Mastering the AS/400, Third Edition, author Jerry Fottral

39. Week 6Sending Messages (Continued) You can use several commands to send messages. Here are four of them: • SNDMSG (Send Message) -- You can use the SNDMSG command interactively or from within a CL program. SNDMSG works only with messages whose text is included within the MSG (Message text) parameter of the command. It can deliver the message to a named message queue or to a user. Mastering the AS/400, Third Edition, author Jerry Fottral

40. Week 6Sending Messages (Continued) • SNDBRKMSG (Send Break Message) -- The SNDBRKMSG command delivers messages only to a workstation message queue. If the workstation is active at the time of delivery, the command interrupts the job and displays the message. If the message is an inquiry message, you can specify a message queue for the response. As with the SNDMSG command, you can use the SNDBRKMSG command interactively or from a CL program, and the message text is part of the command. Mastering the AS/400, Third Edition, author Jerry Fottral

41. Week 6Sending Messages (Continued) • SNDPGMMSG (Send Program Message) -- You can use the SNDPGMMSG command only from within a CL program. You can define the message text within the MSG parameter, or you can use a predefined message that exists in a message file and that has a unique message identifier. The command can deliver its message to any type of message queue, including program and external message queues. For messages requiring a response, you can designate a reply message queue. This command is especially useful when a running program needs to send a message back to the program that called it. Mastering the AS/400, Third Edition, author Jerry Fottral

42. Week 6Sending Messages (Continued) • SNDUSRMSG (Send User Message) -- The SNDUSRMSG command also delivers messages only to a workstation message queue. If the workstation is active at the time of delivery, the command interrupts the job and displays the message. Mastering the AS/400, Third Edition, author Jerry Fottral

43. Week 6Using Concatenation Concatenation is the joining of two character variables or constants. In CL programs, programmers often use concatenation to form messages by combining several character variables and string constants to be assigned to a single variable or to be used as a single message-text value. In fact, concatenation is very often used when a CL program needs to communicate with its user or to send a message to a message queue. Mastering the AS/400, Third Edition, author Jerry Fottral

44. Week 6Creating a CL Program In general, the source code for each CL program is maintained as a member of a source physical file (QCLSRC). Before you can begin coding a source CL program, you need to have created QCLSRC in your library using the CRTSRCPF (Create Source Physical File) command. Mastering the AS/400, Third Edition, author Jerry Fottral

45. Week 6Creating a CL Program (Continued) When you have completed the CL source code, you use the CRTCLPGM (Create CL Program) command to create the *PGM type object. You can key this command on the command line and prompt or, more conveniently, invoke the command from the Work with Members Using PDM screen by taking option 14 on the CLP source member. When the CRTCLPGM command is executed successfully, a new object of type *PGM is created in your library. Mastering the AS/400, Third Edition, author Jerry Fottral