Control Language

CL is the interface to the OS on IBM Power i systems.

Control Lanuage and control languange programs (CLPs) have been the operational interfaces between the operating system and application programs from the IBM System/38 to the AS/400, to the iSeries, and the current power systems architecture.

Command Interface

Control Language (CL) is the user interface to the OS on the IBM Power i Platform. Many CL commands may be executed from a command line. Some are restricted to a Control Language Program (CLP). Therein lies the power of CL, it can be used to create application programs as well as modules and service programs. Over the years, IBM has added new functions to CL to make it a solid tool for system work management, job scheduling, and even application development.It has the added benefit of being able to message individual users, a group of users, or to communicate with SYSOPR, the default system operator profile, with simple commands.

Command

IBM has created a huge library of commands which may be used to drive application functions or system functions. Additionally IBM offers Power i users the facility to create their own commands. CL may be used to create command processing programs or validity checking programs.

/**********************************************************/
/*                                                        */
/* Command..............  SCSIMBRPT                       */
/* Programmer...........  Steven Croy                     */
/*                                                        */
/* Allow execution....... *IPGM,*IREXX,*IMOD,             */
/*                        *BPGM,*BREXX,*BMOD              */
/**********************************************************/
/**********************************************************/
/*                   PROGRAM INTERFACE SECTION            */
/*                                                        */
/* Validity checking Pgm:  SCSIMBRPT                      */
/* Command Processing Pgm: SCS073CL                       */
/*                                                        */
/**********************************************************/

   CMD        PROMPT('SCS IMB Summary report')

   PARM       KWD(DOCTYP) TYPE(*CHAR) LEN(15) RSTD(*YES) +
                SPCVAL((*FIRST 'BA') (*BULK 'BB') (*PROOF +
                'BC') (*IDCARD 'BF')) EXPR(*YES) +
                PROMPT('Document Mailing Type')

   PARM       KWD(STARTDATE) TYPE(*CHAR) LEN(8) MIN(1) +
                CHOICE('Format is *ISO, no separators') +
                PROMPT('Start date YYYYMMDD')

  PARM       KWD(ENDDATE) TYPE(*CHAR) LEN(8) MIN(1) +
                CHOICE('Format is *ISO, no separators') +
               PROMPT('Ending date YYYYMMDD')

  PARM       KWD(VCKEXE) TYPE(*LGL) CONSTANT('1')

The Create Command (CRTCMD) command creates a new user-defined command (that is, a command definition) that can use the same command processing support that is used by IBM-supplied commands. The command definition object, by default, is stored in the general purpose library (QGPL) but may be placed in a user library. To update an existing command (for example, change the name of one of its parameter keywords), the existing command must be deleted by the Delete Command (DLTCMD) command, and then created again by the Create Command (CRTCMD) command. However, some of the values can be changed by the Change Command (CHGCMD) command.

Validity Checker

The command process may be simple with few parameters compiled with instructions directing the command to a program to process the command. Or a command might be created using a command processing program (CPP) and a validity checking program (VCP). In this example the validity checking program makes sure the required parameters are consistent with the values that the command processing program expects. 

/*********************************************************************/
/* Program Name -SCSIMBRPT                                           */
/*                                                                   */
/* Function     - This program was designed as a validity checker    */
/*                for the command SCSIMBRPT                          */
/*                                                                   */
/*                                                                   */
/* Programmer   - Steve Croy                      xx/xx/xxxx         */
/*********************************************************************/
/*********************************************************************/
/*                   Modification log                                */
/*                                                                   */
/*   Date    Programmer      Description                             */
/*********************************************************************/

             PGM        PARM(&SYSPRN &FROMDATE &TODATE &VCKEXE)

             DCL        VAR(&SYSPRN) TYPE(*CHAR) LEN(2)
             DCL        VAR(&FROMDATE) TYPE(*CHAR) LEN(8)
             DCL        VAR(&TODATE) TYPE(*CHAR) LEN(8)
             DCL        VAR(&THISDATE) TYPE(*CHAR) LEN(10)
             DCL        VAR(&VCKEXE)  TYPE(*LGL)  LEN(1)


             DCL        VAR(&ERROR)   TYPE(*DEC)  LEN(3 0)
             DCL        VAR(&MSG)     TYPE(*CHAR) LEN(508)
             DCL        VAR(&MSGDTA)  TYPE(*CHAR) LEN(512)
             DCL        VAR(&MSGID)   TYPE(*CHAR) LEN(7)
             DCL        VAR(&EXIST)  TYPE(*LGL)  LEN(1)
             DCL        VAR(&SYSNAM)  TYPE(*CHAR) LEN(8)

             CHGVAR     VAR(&VCKEXE) VALUE('1')

             /*------------------------------------------------------*/
 STEP1:
             CVTDAT     DATE(&FROMDATE) TOVAR(&THISDATE) +
                          FROMFMT(*ISO) TOFMT(*USA) TOSEP(*NONE)
             MONMSG     MSGID(CPF0000) EXEC(DO)
             SNDPGMMSG  MSG('From date is not valid') TOPGMQ(*SAME)
             MONMSG     MSGID(CPF0000)
             CHGVAR     VAR(&ERROR) VALUE(&ERROR + 1)

             ENDDO

             /*------------------------------------------------------*/
 STEP2:
             CVTDAT     DATE(&TODATE) TOVAR(&THISDATE) FROMFMT(*ISO) +
                          TOFMT(*USA) TOSEP(*NONE)
             MONMSG     MSGID(CPF0000) EXEC(DO)
             SNDPGMMSG  MSG('To date is not valid') TOPGMQ(*SAME)
             MONMSG     MSGID(CPF0000)
             CHGVAR     VAR(&ERROR) VALUE(&ERROR + 1)

             ENDDO

             /*------------------------------------------------------*/
 STEP3:
             IF         COND(&TODATE *LT &FROMDATE) THEN(DO)
             CHGVAR     VAR(&ERROR) VALUE(&ERROR + 1)
             SNDPGMMSG  MSG('To date cannot be greater than from +
                          date') TOPGMQ(*SAME)
             MONMSG     MSGID(CPF0000)
             ENDDO

             IF         COND(&ERROR = 0) THEN(GOTO CMDLBL(EXITPGM))

 RCVMSG:     RCVMSG     MSG(&MSG) MSGDTA(&MSGDTA) MSGID(&MSGID)
             MONMSG     MSGID(CPF0000) EXEC(GOTO CMDLBL(SNDERR))

             IF         COND(&MSG = ' ') THEN(GOTO CMDLBL(SNDERR))

             SNDPGMMSG  MSGID(CPD0006) MSGF(QCPFMSG) MSGDTA('0000' +
                          || &MSG) MSGTYPE(*DIAG)
             MONMSG     MSGID(CPF0000) EXEC(GOTO CMDLBL(SNDERR))
             GOTO       CMDLBL(RCVMSG)

 SNDERR:     SNDPGMMSG  MSGID(CPF0002) MSGF(QSYS/QCPFMSG) MSGTYPE(*ESCAPE)
             MONMSG     MSGID(CPF0000)

 EXITPGM:    ENDPGM

Command Processing Program

The command processing program performs a test before it executes. It checks the environment, and if the program is executing interactively it submits the job. The CL calls an RPG application to produce a report. 

/*********************************************************************/
/* Program Name -SCS073CL                                            */
/*                                                                   */
/* Function     - This program was designed as a command processing  */
/*                program for SCSIMBRPT, a request to print the      */
/*                Missing scans summary report                       */
/*                                                                   */
/* Programmer   - Steve Croy                      xx/xx/xxxx         */
/*********************************************************************/
/*********************************************************************/
/*                   Modification log                                */
/*                                                                   */
/*   Date    Programmer      Description                             */
/*********************************************************************/

             PGM        PARM(&SYSPRN &STARTDATE &ENDDATE)

             DCLPRCOPT  DFTACTGRP(*NO) ACTGRP(SCSRPT) +
                          BNDSRVPGM((SCS000SV))

             DCL        VAR(&Sysprn) TYPE(*CHAR) LEN(2)
             DCL        VAR(&STARTDATE) TYPE(*CHAR) LEN(8)
             DCL        VAR(&ENDDATE) TYPE(*CHAR) LEN(8)
             DCL   VAR(&RPTFOLDER) TYPE(*CHAR) LEN(200)
             DCL   VAR(&MSGKEY)    TYPE(*CHAR) LEN(4)
             DCL   VAR(&PGMNAME)   TYPE(*CHAR) LEN(10)
             DCL   VAR(&FUNCTION)  TYPE(*CHAR) LEN(25)
             DCL   VAR(&PROGRAM)   TYPE(*CHAR) LEN(15)
             DCL   VAR(&SENDER)    TYPE(*CHAR) LEN(80)
             DCL   VAR(&FILEPATH)  TYPE(*CHAR) LEN(200)
             DCL   VAR(&RPTNAME)  TYPE(*CHAR) LEN(40)
             DCL   VAR(&JOBTYPE)   TYPE(*CHAR) LEN(1)
             DCL   VAR(&SYSNAME)   TYPE(*CHAR) LEN(8)
             DCL        VAR(&SUBJECT) TYPE(*CHAR) LEN(50)
             DCL        VAR(&MESSAGE) TYPE(*CHAR) LEN(80)
             DCL        VAR(&REASON) TYPE(*CHAR) LEN(128)
             DCL        VAR(&QT) TYPE(*CHAR) LEN(1) VALUE('''')
             DCL        VAR(&POS) TYPE(*UINT) LEN(2)
             DCL        VAR(&PSS) TYPE(*UINT) LEN(2)

             DCLF       FILE(RPTEMAILL2)

             RTVJOBA    TYPE(&JOBTYPE)
             RTVNETA    SYSNAME(&SYSNAME)

             IF         COND(&JOBTYPE *EQ '1') THEN(DO)
             SBMJOB     CMD(CALL PGM(SCS073CL) PARM(&SYSPRN +
                          &STARTDATE &ENDDATE)) JOB(SCSIMBRPT)
             GOTO       CMDLBL(EXITPGM)
             ENDDO

/*-------------------------------------------------------------------*/
/* Get the program name                                              */
/*-------------------------------------------------------------------*/

             SNDPGMMSG  MSG(' ') TOPGMQ(*SAME) MSGTYPE(*INFO) +
                          KEYVAR(&MSGKEY)
             RCVMSG     PGMQ(*SAME) MSGTYPE(*INFO) RMV(*YES) +
                          SENDER(&SENDER)
             CHGVAR     VAR(&PGMNAME) VALUE(%SST(&SENDER 56 10))
             CHGVAR     VAR(&PROGRAM) VALUE(&PGMNAME)

/*-------------------------------------------------------------------*/
/* Get the folder where the SCS data is to be Archived               */
/*-------------------------------------------------------------------*/

             CHGVAR     VAR(&FUNCTION) VALUE('RPTFOLDER')
             CALL       PGM(SCS005RP) PARM(&PROGRAM &FUNCTION &RPTFOLDER)

/*-------------------------------------------------------------------*/
/* Call the RPG program to produce the report                        */
/*-------------------------------------------------------------------*/

             CALL       PGM(SCS073RP) PARM(&SYSPRN &STARTDATE &ENDDATE)

             CHGVAR     VAR(&RPTNAME) VALUE(&SYSPRN *CAT 'SCAN' *CAT +
                          &STARTDATE *CAT '_' *CAT &ENDDATE *CAT +
                          '.PDF')
             CHGVAR     VAR(&FILEPATH) VALUE(%trim(&RPTFOLDER) +
                          *TCAT &RPTNAME)
/*-------------------------------------------------------------------*/
/* Copy the output to a PDF                                          */
/*-------------------------------------------------------------------*/

             CPYSPLF    FILE(SCS073PR) TOFILE(*TOSTMF) SPLNBR(*LAST) +
                          TOSTMF(&FILEPATH) WSCST(*PDF) +
                          STMFOPT(*REPLACE)

             OVRDBF     FILE(RPTEMAILL2) TOFILE(RPTEMAILL2) +
                          POSITION(*KEYAE 1 *N &PROGRAM) +
                          OVRSCOPE(*CALLLVL)
             RCVF
             MONMSG     MSGID(CPF0864) EXEC(DO)
                GOTO       TERMINATE
             ENDDO

             addlible   lib(ALLFTM100)
             monmsg     CPF2103

             CHGVAR     VAR(&SUBJECT) VALUE(&RPTNAME)
             CHGVAR     VAR(&MESSAGE) VALUE('The IMB summary has +
                          been completed. Check the document to +
                          review the output.')
             CHGVAR     VAR(&REASON) VALUE('The report is output +
                          only. No file is updated in this process.')

             CHGVAR     VAR(&POS) VALUE(1)
             DOUNTIL    COND(&POS *EQ 0)
             CHGVAR     VAR(&POS) VALUE(%SCAN('/' &RPTFOLDER &POS))
             IF         COND(&POS *GT 0) THEN(DO)
             CHGVAR     VAR(&PSS) VALUE(&POS)
             CHGVAR     VAR(&POS) VALUE(&POS + 1)
             ENDDO      /* End do */
             ENDDO      /* End Do Until */

             CHGVAR     VAR(%SST(&RPTFOLDER 1 1)) VALUE(' ')
             CHGVAR     VAR(%SST(&RPTFOLDER &PSS 1)) VALUE(' ')
             CHGVAR     VAR(&RPTFOLDER) VALUE(%TRIM(&RPTFOLDER))

             ALLFTM100/SENDMAIL TO(&EMAILADDR) FROM(&FROMADDR) +
                          REPLYTO(&REPLYTO) SUBJECT(&SUBJECT) +
                          MESSAGE(&MESSAGE &REASON) ATCTYPE(*IFS) +
                          ATCNAME(&RPTNAME) ATCPATH(&RPTFOLDER) +
                          ATCPNAME(&RPTNAME)

             DLTSPLF    FILE(SCS073PR) SPLNBR(*LAST)
             MONMSG     MSGID(CPF0000)
 TERMINATE:

             DLTOVR     FILE(RPTEMAILL2) LVL(*)
             MONMSG     MSGID(CPF0000)
 EXITPGM:    RETURN

             ENDPGM

In this example, the CPP adds a library for a third-party vendor product. The output is archived, then emailed to a receipient through the licesnsed software in a product library.