APPL

For creating CICS applications:

For creating Db2 or MQ applications:

For creating IMS applications:

For creating batch applications:

For creating WAS applications:

Syntax explanations

• Name is a one to eight-character name to be assigned to the application. Name can consist of the uppercase characters A through Z, 0 through 9, the #, the ?, the *, and the _ character. Any other character will be translated to its uppercase equivalent for A through Z or the # character. Be careful when using the following special name values to avoid combining data because of these translation rules.
• You can use special or reserved name values for defining applications:
  • @TRANID can be used to create a specific application where the name is the transaction name as determined by UIE. This creates a unique application for each unique transaction name that matches the APPL command criteria.
  • @PRIME creates a unique application based on the value found in the PRIMARY GROUPING field (that is, PLAN, TRAN, PROG, and so on).

  • @SECOND creates a unique application based on the value found in the SECONDARY GROUPING field.

    Important

    Because @TRANID, @PRIME and @SECOND are reserved keywords that request a function, you cannot create an application with the name @TRANID, @PRIME or @SECOND.

  • OFFSET:LENGTH When using @PRIME, @SECOND, or @TRANID, the APPL name is created from the value contained in the primary or secondary grouping or tran ID field, starting at offset 1, for a length of 8 characters. You can optionally specify an offset and length value to use only a subset of the value in these fields as the APPL name. The syntax value for this field is x:y, where x is the starting offset and y is the length. A single value x (that is, (2)) can be specified if you only want to change the starting offset value. A single value y preceded by a colon (that is, (:2)) can be specified if you only want to change the length value. For example, if your CICS transaction names contain a special two character code in the second and third character of the transaction name and TRAN is the primary grouping for CICS, you can specify the following command to use just these two characters as the APPL name:

    APPL @PRIME(2:2) SUBSYSTYPE=CICS
• The SUBSYSTYPE subparameter is a required value that indicates the subsystem type for the APPL command and can have the values:
  • CICS–All CICS records and matched CICS-Db2, CICS-IMS and CICS-MQ data
  • Db2–All non-subsystem Db2 records and any unmatched CICS-Db2 or IMS-Db2 records
  • IMS–All IMS records and matched IMS-Db2 and IMS-MQ data
  • MQ–All non-subsystem MQ records and any unmatched CICS-MQ or IMS-MQ records
  • BATCH–All SMF 30 records
  • WAS–All WebSphere Application Server records
• SID and SUBSYS are comma separated lists of system IDs and subsystem IDs, respectively. Subsystem ID applies to Db2, IMS, or MQ.
  • The absence of SID_LIST means that this command applies to all SIDs.
  • The absence of SUBSYS_LIST means that this command applies to all SUBSYS IDs.
  • An element of a SUBSYS_ID LIST can contain a pattern or list of patterns.
• The REGTYPE subparameter indicates the region type for an IMS region. This can have one of the default values: IMSMPP, IMSBMP, DBC, FPU, or CPI. This can also be a name used in the COMBINE command. REGTYPE accepts a list of explicit values. REGTYPE accepts a list of explicit values as described in this paragraph. REGTYPE can be lists of types. For more information, see UIE-concepts.
• The IMSREGION subparameter indicates the IMS region name for this APPL command. This can be a list of values or patterns.
• The CONNTYPE subparameter indicates the connection type for Db2 and MQ subsystems. For Db2, this can have the values: TSO, DB2CALL, DLIBATCH, CICS, IMSBMP, IMSMPP, SYSDIRAC, APPDIRAC, IMSCNTL, TSOBATCH, UTILITY, or RRSAF. For MQ, this can have the values: CICS, MVSTSO, IMSCNTL, IMSMPP, SERVER, CHANNEL or RRSBATCH. This can also be a name used in the COMBINE command. CONNTYPE accepts a list of explicit values as described in this paragraph. CONNTYPE can be lists of types. For more information, see UIE-concepts.
• The CONNAME subparameter indicates the Db2 or MQ connection name for this APPL command. This can be a list of values or patterns.
• The CICSREGION subparameter indicates the CICS region name for this APPL command. This can be a list of values or patterns.
• The CICSJOB subparameter indicates the jobname for the CICS region for this APPL command. This can be a list of values or patterns.
• The SERVER subparameter indicates the WAS server name for this APPL command. This can be a list of values in patterns.
• The CONTAINER subparameter indicates the WAS container type for this APPL command. This can be J2EE for J2EE container data (from SMF type 120 subtype 6 records), REQUEST for Server Request data (from SMF type 120 subtype 9 records), or WEB for Web Application data (from SMF type 120 subtype 8 records).
• The PRIMEVAL subparameter is based on the primary transaction grouping value defined for the SUBSYSTYPE and should contain the actual value for the primary transaction grouping keyword or a pattern containing the wild card character. For example, if the primary transaction grouping for CICS is set to TRAN, then the value for the PRIMEVAL subparameter would be an actual CICS transaction name.
  • In the type 120 records, the AMCname can be up to 256 characters, the method name can be up to 512 characters, and the Warname (web application) and Servlet names can be up to 128 characters. To reduce DASD space and processing time, UIE only keeps one to sixteen characters from each of these fields. The value that you specify for the PRIMEVAL or SECONDVAL fields is used as a pattern to be matched against the actual value in the type 120 record. For example, if PRIMEKEY is METHOD and you specify PRIMEVAL=CREATE*, UIE searches the entire 512 characters of the METHOD field for a match on the pattern CREATE. If a match for the pattern is found, that transaction is assigned to the corresponding APPL.
  • For an APPL command with the SUBSYSTYPE of WAS, if the APPLGROUPING PRIMEKEY or SECONDKEY value is TYPE, the APPL PRIMEVAL or SECONDVAL value should be one of the following values:
    • IIOP
    • INTERNAL
    • HTTP
    • HTTPS
    • MBEAN
    • MDBPLANA
    • MDBPLANB
    • MDBPLANC
    • OTS
    • SIP
    • UNKNOWN

• The SECONDVAL subparameter is based on the secondary transaction grouping value defined for the SUBSYSTYPE and should contain the actual value for the secondary transaction grouping keyword or a pattern containing the wild card character. For example, if the secondary transaction grouping for Db2 is set to PLAN, then the value for the SECONDVAL subparameter would be an actual Db2 plan name.

  Important

  SID, SUBSYS, CICSREGION, CONNAME, IMSREGION, CICSJOB, PRIMEVAL and SECONDVAL accept a list of values or patterns, as follows:

  A pattern can be a combination of the wildcard character *, the wild character ?, and standard EBCDIC characters. An * denotes 0 or more characters preceding and/or following a character string. A ? denotes that any character can appear in this position within the string. The pattern cannot exceed the field length of the element. A maximum of three * are allowed per pattern.

  Some valid patterns for an 8-byte element can be:

  AB*
  *AB
  *AB*
  *A*B
  *A*B*
  ????????
  ??*ABC
  *A??B*

• The APPLPREFIX subparameter can be used in combination with the special @keyword APPL names (@TRANID, @PRIME, @SECOND) to form an APPL name that consists of the APPLPREFIX + @keyword value. If the length of the resulting concatenation exceeds the length of the APPL name field (currently 10 characters), the resulting value is truncated on the right. For example, if you specify the command:

  APPL @TRANID SUBSYSTYPE=CICS APPLPREFIX=CICS

  The APPL names for CICS applications will be CICS+tranname (such as, CICSABCD, CICSCESN, and so on).

• The APPLSUFFIX subparameter can be used in combination with the special @keyword APPL names (@TRANID, @PRIME, @SECOND) to form an APPL name that consists of @keyword value + APPLSUFFIX. If the length of the resulting concatenation exceeds the length of the APPL name field (currently 10 characters), the resulting value is truncated on the right. For example, if you specify the command.

  APPL @TRANID SUBSYSTYPE=CICS APPLPSUFFIX=CICS

  The APPL names for CICS applications will be tranname+CICS (such as, ABCDCICS, CESNCICS, and so on).

• The REPORT subparameter can be used to generate a report showing the data composition of the application when you specify YES. This subparameter is optional. When you specify DATA or BOTH, a comma delimited file of the TRWA data used to create the report and XML files is produced in the same sequence as the report. The data file is written to the DDname PCTRWA and this DDname must be present in the JCL if DATA is requested. The PCTRWA file must have a record format of VB and a LRECL of 4096 bytes. For more information about report, see UIE-Application-report.

• The TRANDETAIL subparameter is optional and can be used to create Visualizer tables containing the transaction detail that makes up the APPLication when you specify YES or ALL. The default value is NO. When you specify ALL, every APPL command with the same <name> will have TRANDETAIL set to YES. You can use ALL when you are using multiple APPL commands to define a single APPLication. Specifying ALL makes it possible to get Visualizer transaction detail for an entire APPLication without changing every APPL command in the command file.

  Important

  TRANDETAIL produces Visualizer transaction table data only for the APPLs specified. To create transaction detail data for all APPLs, including the defaults, see INCLUDETBL=TRANDETAIL in the VISFILE.

• The SLR subparameter indicates whether SLR values should be accumulated for this application.
• The CAT subparameter is a one to eight character value that defines a category for this application. Category is used as an additional grouping label for SLR processing.

• The SUITE subparameter indicates the SUITE name for this APPL command. This is a single SUITE name value.

  Important

  A batch application can include several SUITEs, but in this case, you should use several APPL commands, one for each SUITE name.

• The GOALRESP subparameter can be used to set specific SLR response time goals for the application defined by this APPL command. These values override the default values specified in the SLRPARMS command. The GOALRESP subparameter must be a comma separated list of up to four values. Each value must be a number that represents a response time value. This number can contain a decimal point.

• The GOALPCT subparameter can be used to set specific SLR response time goal percentages for the application defined by this APPL command. These values override the default values specified in the SLRPARMS command. The GOALPCT subparameter must be a comma separated list of up to four values. Each value must be a number that represents a percent value from 0 to 100. This number can contain a decimal point.

  Important

  The number of elements in the lists of GOALRESP and GOALPCT parameters must be the same as the number of groups defined in the SLRPARMS command for this subsystem type.

Rules

• All subparameters in the APPL command, except application name, and SUBSYSTYPE are optional.
• The APPL command can be split into several lines only in the blank position, that is, it is possible to put a subparameter on a separate line. However, you should not split the line in the middle of <LIST parms>, on an '=' character and so on.
• The APPL command with the same name can be repeated several times.
• APPL commands with the same name do not need to be grouped together.
• The position of the commands is important. UIE uses APPL command in the following manner:
  • While reading the command file, UIE analyzes the syntax of all commands and stores each APPL command with its parameters sequentially in the same order that they are encountered in the command file.

  • During subsystem data processing, UIE analyzes each element of data and tries to match it with the application definitions in the order that they were specified in the command file. As soon as a particular data element matches an application definition, the APPL name is assigned, and UIE continues to analyze the next data element. For example, if a command file contains the following commands and PRIMEVAL was specified as TRAN:

    APPL CICS_ABC SUBSYSTYPE=CICS PRIMEVAL=ABC*
    APPL CICS_AB SUBSYSTYPE=CICS PRIMEVAL=AB*
    APPL CICS_A SUBSYSTYPE=CICS PRIMEVAL=A*

    • All CICS transactions on all SIDs that start with ABC are placed into application CICS_ABC.
    • All CICS transactions on all SIDs that start with AB, but do not have C as the third character, are placed into application CICS_AB.
    • All CICS transactions on all SIDs that start with A, but do not have B as the second character, are placed into application CICS_A.
• In the PRIMEVAL or SECONDVAL parameter, a question mark can be specified as a wildcard character, and a comma is used to separate multiple primary or secondary values. To indicate that a question mark or comma are part of primary or secondary transaction value and are not being used as a wildcard or separator value, enclose the primary or secondary value in single quotes, for example PRIMEVAL='?ABC'. 

Defining applications when subsystem data combination is requested

If you have requested that UIE combine subsystem data that makes a call or request in another subsystem, be aware of the following rules when defining applications.

• If you have turned on CICS MRO processing, you should define applications based on the initiating transaction in a CICS unit-of-work. This is usually the transaction that executes in a CICS Terminal Owning Region (TOR). You do not need to define applications for the remote transactions in the CICS unit-of-work, which are usually transactions in an Application Owning Region (AOR) or a File Owning Region (FOR). When CICS MRO processing is turned on, UIE matches CICS transactions based on the Unit-of-Work ID of the initiating transaction.

• If you have turned on the combining of CICS and Db2 data, you should define applications based on your CICS transactions. You do not have to define applications for any Db2-CICS transactions. When the CICS and Db2 data is combined, UIE matches Db2 transactions to the CICS transactions that call Db2, based on the CICS Unit-Of-Work ID. The matching Db2 transaction is placed into the application for the corresponding CICS transaction.

  For Db2 data with a connection type of CICS that does not match any Unit-of-Work ID and when the matching of CICS and Db2 is turned off, the APPL commands with a SUBSYSTYPE of Db2 are checked first for a match followed by the APPL commands with a SUBSYSTYPE of CICS.

• If you have turned on the combining of CICS and IMS data and you are using DBCTL, you should define applications based on your CICS transactions. You do not have to define applications for any IMS-CICS transactions. When the CICS and IMS data is combined, UIE matches IMS transactions to the CICS transactions that call IMS, based on the CICS Unit-Of-Work ID. The matching IMS transaction is placed into the application for the corresponding CICS transaction.

• If you have turned on the combining of CICS and MQ data, you should define applications based on your CICS transactions. You do not need to define applications for any MQ-CICS transactions. When the CICS and MQ data is combined, UIE matches MQ transactions to the CICS transactions that call MQ based on the CICS Unit-Of-Work ID. The matching MQ transaction is placed into the application for the corresponding CICS transaction.

  For MQ data with a connection type of CICS that does not match any Unit-of-Work ID and when the matching of CICS and MQ is turned off, the APPL commands with a SUBSYSTYPE of MQ are checked first for a match followed by the APPL commands with a SUBSYSTYPE of CICS.

• If you have turned on the combining of IMS and Db2 data, you should define applications based on your IMS transactions. You do not have to define applications for any Db2-IMS transactions. When the IMS and Db2 data is combined, UIE matches Db2 transactions to the IMS transactions that call Db2, based on the IMS PSBname and userid. The matching Db2 transaction is placed into the application for the corresponding IMS transaction.

  For Db2 data with any of the connection types for IMS that does not match any IMS record and when the matching of IMS and Db2 is turned off, the APPL commands with a SUBSYSTYPE of Db2 are checked first for a match followed by the APPL commands with a SUBSYSTYPE of IMS.

• If you have turned on the combining of IMS and MQ data, you should define applications based on your IMS transactions. You do not need to define applications for any MQ-IMS transactions. When the IMS and MQ data is combined, UIE matches transactions to the IMS transactions that call MQ based on the IMS PSBname and userid. The matching MQ transaction is placed into the application for the corresponding IMS transaction.

  For MQ data with any of the connection types for IMS that does not match any IMS record and when the matching of IMS and MQ is turned off, the APPL commands with a SUBSYSTYPE of MQ are checked first for a match followed by the APPL commands with a SUBSYSTYPE of IMS.

Examples

• Create two applications that contain Db2 batch update and Db2 batch purge jobs. The CONNTYPE of BATCH was created by the COMBINE command. See the examples in COMBINE.

  APPL DB2UPD SUBSYSTYPE=DB2
              CONNTYPE=BATCH
              CONNAME=DUPDATE1,DUPDATE2,DUPDATEA
  
  APPL DB2PUR SUBSYSTYPE=DB2
              CONNTYPE=BATCH
              CONNAME=DPURGEX,DPURGEY,DPURGEZ

• Create three applications for all IMS systems by message type. The REGTYPE of IMSFP results from the use of the COMBINE command. See the examples in COMBINE.

  APPL MESSPROS SUBSYSTYPE=IMS
                REGTYPE=IMSMPP
  
  APPL BMPPROS  SUBSYSTYPE=IMS
                REGTYPE=IMSBMP
  
  APPL FASTPATH SUBSYSTYPE=IMS
                REGTYPE=IMSFP

• The following is an example of a CICS system running on logical system SYSA. Four applications need to be defined based on the appearance of certain characters in the transaction name, which is the default primary field value. And all other CICS transactions are placed in the OTHER workload.

  APPL PAYROLL  SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=PR*
  
  APPL ACCPAY   SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=AC*
  
  APPL ACCREC   SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=*AR
  
  APPL INVENTOR PAYROLL SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=*IN*
  
  APPL ALLOTHER SUBSYSTYPE=CICS
                SID=SYSA

• Using this same example and changing the PRIMEVAL to a single character, can lead to different results. If an INVENTOR transaction is PI12, because the commands are scanned in order, it will fall into the PAYROLL application. Placing the APPL INVENTOR command first solves this problem, but other transactions, such as AA12, which might belong in ACCREC, can end up in ACCPAY. The order and the amount of qualification is important.

  APPL PAYROLL  SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=P*
  
  APPL ACCPAY   SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=A*
  
  APPL ACCREC   SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=*A
  
  APPL INVENTOR SUBSYSTYPE=CICS
                SID=SYSA
                PRIMEVAL=*I*
  
  APPL ALLOTHER SUBSYSTYPE=CICS
                SID=SYSA

• We want to put all Db2 DDF transactions into an application called REMOTE.

  APPL REMOTE SUBSYSTYPE=DB2
              SID=SYSX
              CONNTYPE=APPDIRAC,SYSDIRAC

• Putting it all together, we might have one production IMS and Db2 system and one test IMS and Db2 system running on separate logical systems. Production is IMSP and DB2P, and test is DB2T and IMST. All of the IMS systems have PSB and transaction names that relate to a business function. Payroll PSBs begin with PR, Human Resources begin with HR, and Inventory begins with IN. The transaction names correspond to the activity within the business unit. We also want to break down the transactions by message type. Logically, we will group the IMS data by PSB name and transaction because the message type is automatically part of the key. Additionally, we do not want to match any of our IMST test data. The following application commands can accomplish this task:

  *TURN OFF MATCHING FOR IMST SUBSYSTEM
  APPLCONTROL   SUBSYSTYPE=IMS
                SUBSYS=IMST
                IMSMATCH=NO
  
  *COMBINE ALL FASTPATH INTO ONE MESSAGE TYPE ON ALL SYSTEMS
  COMBINE IMSFP SUBSYSTYPE=IMS
                REGTYPE=FP,WFP,QFP,MFP,WMFP,QMFP
  
  *GROUP BY PSB AND TRANSACTION
  APPLGROUPING  SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEKEY=PSB
                SECONDKEY=TRAN
  
  *DEFINE APPLICATIONS BY IMS TRANSACTION TAKE THE DEFAULTS IN IMST
  APPL HRADD    SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEVAL=HR*
                SECONDVAL=HRADD*
  
  APPL HRUPD    SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEVAL=HR*
                SECONDVAL=HRUPD*
  
  APPL HRCANFP  SUBSYSTYPE=IMS
                SUBSYS=IMSP
                REGTYPE=IMSFP
                PRIMEVAL=HR*
                SECONDVAL=HRDEL*
  
  APPL PRRAISE  SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEVAL=PR*
                SECONDVAL=PRBUCKS
  
  APPL PROTHER  SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEVAL=PR*
                SECONDVAL=PR*
  
  APPL ALLINVEN SUBSYSTYPE=IMS
                SUBSYS=IMSP
                PRIMEVAL=IN*
  
  APPL OTHERMPP SUBSYSTYPE=IMS
                SUBSYS=IMSP
                REGTYPE=IMSMPP
  
  APPL OTHERFP  SUBSYSTYPE=IMS
                SUBSYS=IMSP
                REGTYPE=IMSFP
  
  APPL OTHERBMP SUBSYSTYPE=IMS
                SUBSYS=IMSP
                REGTYPE=IMSBMP